Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

std: Stabilize APIs for the 1.10 release #33699

Merged
merged 1 commit into from
May 26, 2016

Conversation

alexcrichton
Copy link
Member

@alexcrichton alexcrichton commented May 17, 2016

This commit applies the FCP decisions made by the libs team for the 1.10 cycle,
including both new stabilizations and deprecations. Specifically, the list of
APIs is:

Stabilized:

  • os::windows::fs::OpenOptionsExt::access_mode
  • os::windows::fs::OpenOptionsExt::share_mode
  • os::windows::fs::OpenOptionsExt::custom_flags
  • os::windows::fs::OpenOptionsExt::attributes
  • os::windows::fs::OpenOptionsExt::security_qos_flags
  • os::unix::fs::OpenOptionsExt::custom_flags
  • sync::Weak::new
  • Default for sync::Weak
  • panic::set_hook
  • panic::take_hook
  • panic::PanicInfo
  • panic::PanicInfo::payload
  • panic::PanicInfo::location
  • panic::Location
  • panic::Location::file
  • panic::Location::line
  • ffi::CStr::from_bytes_with_nul
  • ffi::CStr::from_bytes_with_nul_unchecked
  • ffi::FromBytesWithNulError
  • fs::Metadata::modified
  • fs::Metadata::accessed
  • fs::Metadata::created
  • sync::atomic::Atomic{Usize,Isize,Bool,Ptr}::compare_exchange
  • sync::atomic::Atomic{Usize,Isize,Bool,Ptr}::compare_exchange_weak
  • collections::{btree,hash}_map::{Occupied,Vacant,}Entry::key
  • os::unix::net::{UnixStream, UnixListener, UnixDatagram, SocketAddr}
  • SocketAddr::is_unnamed
  • SocketAddr::as_pathname
  • UnixStream::connect
  • UnixStream::pair
  • UnixStream::try_clone
  • UnixStream::local_addr
  • UnixStream::peer_addr
  • UnixStream::set_read_timeout
  • UnixStream::set_write_timeout
  • UnixStream::read_timeout
  • UnixStream::write_Timeout
  • UnixStream::set_nonblocking
  • UnixStream::take_error
  • UnixStream::shutdown
  • Read/Write/RawFd impls for UnixStream
  • UnixListener::bind
  • UnixListener::accept
  • UnixListener::try_clone
  • UnixListener::local_addr
  • UnixListener::set_nonblocking
  • UnixListener::take_error
  • UnixListener::incoming
  • RawFd impls for UnixListener
  • UnixDatagram::bind
  • UnixDatagram::unbound
  • UnixDatagram::pair
  • UnixDatagram::connect
  • UnixDatagram::try_clone
  • UnixDatagram::local_addr
  • UnixDatagram::peer_addr
  • UnixDatagram::recv_from
  • UnixDatagram::recv
  • UnixDatagram::send_to
  • UnixDatagram::send
  • UnixDatagram::set_read_timeout
  • UnixDatagram::set_write_timeout
  • UnixDatagram::read_timeout
  • UnixDatagram::write_timeout
  • UnixDatagram::set_nonblocking
  • UnixDatagram::take_error
  • UnixDatagram::shutdown
  • RawFd impls for UnixDatagram
  • {BTree,Hash}Map::values_mut
  • <[_]>::binary_search_by_key

Deprecated:

  • StaticCondvar - this, and all other static synchronization primitives
    below, are usable today through the lazy-static crate on
    stable Rust today. Additionally, we'd like the non-static
    versions to be directly usable in a static context one day,
    so they're unlikely to be the final forms of the APIs in any
    case.
  • CONDVAR_INIT
  • StaticMutex
  • MUTEX_INIT
  • StaticRwLock
  • RWLOCK_INIT
  • iter::Peekable::is_empty

Closes #27717
Closes #27720
Closes #30014
Closes #30425
Closes #30449
Closes #31190
Closes #31399
Closes #31767
Closes #32111
Closes #32281
Closes #32312
Closes #32551
Closes #33018

@rust-highfive
Copy link
Collaborator

r? @brson

(rust_highfive has picked a reviewer for you, use r? to override)

@alexcrichton
Copy link
Member Author

Still working through the tests, but this should have all the real meat.

r? @aturon
cc @rust-lang/libs

@rust-highfive rust-highfive assigned aturon and unassigned brson May 17, 2016
@@ -14,6 +14,8 @@

#[stable(feature = "rust1", since = "1.0.0")]
pub use self::c_str::{CString, CStr, NulError, IntoStringError};
#[stable(feature = "rust1", since = "1.0.0")]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are the feature and the version here correct?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch!

@alexcrichton alexcrichton force-pushed the stabilize-1.10 branch 3 times, most recently from 2e3600c to 7c03658 Compare May 18, 2016 23:02
@alexcrichton
Copy link
Member Author

@SimonSapin brings up that write_utf{8,16} could possibly panic instead of returning a result.

@sfackler
Copy link
Member

I think I like that approach given that there's an obvious and reasonable upper bound on the buffer size.

@alexcrichton
Copy link
Member Author

I personally feel that it's inconsistent with how we handle encoding/decoding everywhere else, which is to use a result instead of panicking

@SimonSapin
Copy link
Contributor

@alexcrichton what APIs and errors are you thinking of, specifically? Providing a buffer smaller than four bytes or two 16-bit units is a different kind of error than, for example, the input containing ill-formed byte sequences. It’s easy to use something like [u8; 4] or vec.reserve(4), while many programs deal with unpredictable input.

And, as I argued in #27784 (comment), would callers ever do anything other than .unwrap() that Result?

@alexcrichton
Copy link
Member Author

The major examples are str::from_utf8 and String::from_utf16. I could imagine that callers may not be moving into a stack-local buffer (but perhaps a Vec) and they want to optimize a path where something is one byte or less (or something like that).

@SimonSapin
Copy link
Contributor

These examples don’t take a caller-provided buffer, so the "buffer too short" kind of error doesn’t happen there.

If the caller of char::write_utf8 / char::write_utf16 wants an exact size rather than an upper bound, they can use char::len_utf8 / char::len_utf16.

@alexcrichton
Copy link
Member Author

Yes they're only analogous in the sense that they don't panic, they return results on encoding/decoding operations. The buffer may not always be controlled by the caller, but some utility function would be given a buffer from elsewhere in which case it'd just always have to perform this validation. Essentially you will 100% of the time need this check for length unless you're calling with a buffer you created yourself, and that's probably not 100% of use cases.

@SimonSapin
Copy link
Contributor

Outside of tests, rust-lang/rust currently contains 9 uses of encode_utf8 that would be replaced with write_utf8:

  • 3 (in collections::string) extend a Vec<u8>, so they could use either vec.reserve(4) or vec.reserve(c.len_utf8()).
  • 6 (in core::fmt, serialize::json, and std::sys::common::wtf8) then use str::from_utf8_unchecked, they could use a [u8; 4] buffer.

100% would statically ensure they provide a large enough buffer to write_utf8.

(I found zero usage in Servo and its dependencies that I’ve ever checked out. When #[unstable] was introduced we replaced them with write! into a [u8; 4] buffer.)

I really don’t see a scenario where "some utility function given a buffer from elsewhere" would be useful.

@aturon
Copy link
Member

aturon commented May 23, 2016

I agree with @SimonSapin here, a too-short buffer seems reasonable to treat as a contract violation.

@alexcrichton
Copy link
Member Author

I'd be pretty uncomfortable stabilizing an API with a brand new name, new semantics, and a new return type all at once. This may also miss the beta branch now and need to be backported. Shall we just leave it out for another round?

@alexcrichton
Copy link
Member Author

Ok, I've backed out those API additions, re-r? @aturon

@aturon
Copy link
Member

aturon commented May 23, 2016

@alexcrichton I've reviewed the rest of the PR (LGTM), but I don't see the updates backing out these recent additions.

@alexcrichton
Copy link
Member Author

@bors: r=aturon 91e8b4c57eafc0b4dc577bfab6a2685e635c9bed

@bors
Copy link
Contributor

bors commented May 23, 2016

🙀 91e8b4c57eafc0b4dc577bfab6a2685e635c9bed is not a valid commit SHA. Please try again with 7c03658.

@alexcrichton
Copy link
Member Author

@bors: r=aturon 91e8b4c57eafc0b4dc577bfab6a2685e635c9bed

@bors
Copy link
Contributor

bors commented May 23, 2016

⌛ Testing commit 91e8b4c with merge b07d438...

@bors
Copy link
Contributor

bors commented May 23, 2016

💔 Test failed - auto-mac-64-opt

@alexcrichton
Copy link
Member Author

@bors: r=aturon

@bors
Copy link
Contributor

bors commented May 24, 2016

📌 Commit 04eff6c has been approved by aturon

@bors
Copy link
Contributor

bors commented May 24, 2016

⌛ Testing commit 04eff6c with merge 05765aa...

@bors
Copy link
Contributor

bors commented May 24, 2016

💔 Test failed - auto-win-gnu-32-opt-rustbuild

This commit applies the FCP decisions made by the libs team for the 1.10 cycle,
including both new stabilizations and deprecations. Specifically, the list of
APIs is:

Stabilized:

* `os::windows::fs::OpenOptionsExt::access_mode`
* `os::windows::fs::OpenOptionsExt::share_mode`
* `os::windows::fs::OpenOptionsExt::custom_flags`
* `os::windows::fs::OpenOptionsExt::attributes`
* `os::windows::fs::OpenOptionsExt::security_qos_flags`
* `os::unix::fs::OpenOptionsExt::custom_flags`
* `sync::Weak::new`
* `Default for sync::Weak`
* `panic::set_hook`
* `panic::take_hook`
* `panic::PanicInfo`
* `panic::PanicInfo::payload`
* `panic::PanicInfo::location`
* `panic::Location`
* `panic::Location::file`
* `panic::Location::line`
* `ffi::CStr::from_bytes_with_nul`
* `ffi::CStr::from_bytes_with_nul_unchecked`
* `ffi::FromBytesWithNulError`
* `fs::Metadata::modified`
* `fs::Metadata::accessed`
* `fs::Metadata::created`
* `sync::atomic::Atomic{Usize,Isize,Bool,Ptr}::compare_exchange`
* `sync::atomic::Atomic{Usize,Isize,Bool,Ptr}::compare_exchange_weak`
* `collections::{btree,hash}_map::{Occupied,Vacant,}Entry::key`
* `os::unix::net::{UnixStream, UnixListener, UnixDatagram, SocketAddr}`
* `SocketAddr::is_unnamed`
* `SocketAddr::as_pathname`
* `UnixStream::connect`
* `UnixStream::pair`
* `UnixStream::try_clone`
* `UnixStream::local_addr`
* `UnixStream::peer_addr`
* `UnixStream::set_read_timeout`
* `UnixStream::set_write_timeout`
* `UnixStream::read_timeout`
* `UnixStream::write_Timeout`
* `UnixStream::set_nonblocking`
* `UnixStream::take_error`
* `UnixStream::shutdown`
* Read/Write/RawFd impls for `UnixStream`
* `UnixListener::bind`
* `UnixListener::accept`
* `UnixListener::try_clone`
* `UnixListener::local_addr`
* `UnixListener::set_nonblocking`
* `UnixListener::take_error`
* `UnixListener::incoming`
* RawFd impls for `UnixListener`
* `UnixDatagram::bind`
* `UnixDatagram::unbound`
* `UnixDatagram::pair`
* `UnixDatagram::connect`
* `UnixDatagram::try_clone`
* `UnixDatagram::local_addr`
* `UnixDatagram::peer_addr`
* `UnixDatagram::recv_from`
* `UnixDatagram::recv`
* `UnixDatagram::send_to`
* `UnixDatagram::send`
* `UnixDatagram::set_read_timeout`
* `UnixDatagram::set_write_timeout`
* `UnixDatagram::read_timeout`
* `UnixDatagram::write_timeout`
* `UnixDatagram::set_nonblocking`
* `UnixDatagram::take_error`
* `UnixDatagram::shutdown`
* RawFd impls for `UnixDatagram`
* `{BTree,Hash}Map::values_mut`
* `<[_]>::binary_search_by_key`

Deprecated:

* `StaticCondvar` - this, and all other static synchronization primitives
                    below, are usable today through the lazy-static crate on
                    stable Rust today. Additionally, we'd like the non-static
                    versions to be directly usable in a static context one day,
                    so they're unlikely to be the final forms of the APIs in any
                    case.
* `CONDVAR_INIT`
* `StaticMutex`
* `MUTEX_INIT`
* `StaticRwLock`
* `RWLOCK_INIT`
* `iter::Peekable::is_empty`

Closes rust-lang#27717
Closes rust-lang#27720
cc rust-lang#27784 (but encode methods still exist)
Closes rust-lang#30014
Closes rust-lang#30425
Closes rust-lang#30449
Closes rust-lang#31190
Closes rust-lang#31399
Closes rust-lang#31767
Closes rust-lang#32111
Closes rust-lang#32281
Closes rust-lang#32312
Closes rust-lang#32551
Closes rust-lang#33018
@alexcrichton
Copy link
Member Author

@bors: r=aturon

@bors
Copy link
Contributor

bors commented May 24, 2016

📌 Commit cae91d7 has been approved by aturon

@bors
Copy link
Contributor

bors commented May 25, 2016

⌛ Testing commit cae91d7 with merge 07399eb...

@bors
Copy link
Contributor

bors commented May 25, 2016

💔 Test failed - auto-win-gnu-32-opt-rustbuild

@alexcrichton
Copy link
Member Author

@bors: retry

Praying that's spurious, I'll open an issue if I see it again

@bors
Copy link
Contributor

bors commented May 25, 2016

⌛ Testing commit cae91d7 with merge 991b0fa...

@bors
Copy link
Contributor

bors commented May 25, 2016

💔 Test failed - auto-win-msvc-64-opt

@bors
Copy link
Contributor

bors commented May 26, 2016

⌛ Testing commit cae91d7 with merge d5759a3...

bors added a commit that referenced this pull request May 26, 2016
std: Stabilize APIs for the 1.10 release

This commit applies the FCP decisions made by the libs team for the 1.10 cycle,
including both new stabilizations and deprecations. Specifically, the list of
APIs is:

Stabilized:

* `os::windows::fs::OpenOptionsExt::access_mode`
* `os::windows::fs::OpenOptionsExt::share_mode`
* `os::windows::fs::OpenOptionsExt::custom_flags`
* `os::windows::fs::OpenOptionsExt::attributes`
* `os::windows::fs::OpenOptionsExt::security_qos_flags`
* `os::unix::fs::OpenOptionsExt::custom_flags`
* `sync::Weak::new`
* `Default for sync::Weak`
* `panic::set_hook`
* `panic::take_hook`
* `panic::PanicInfo`
* `panic::PanicInfo::payload`
* `panic::PanicInfo::location`
* `panic::Location`
* `panic::Location::file`
* `panic::Location::line`
* `ffi::CStr::from_bytes_with_nul`
* `ffi::CStr::from_bytes_with_nul_unchecked`
* `ffi::FromBytesWithNulError`
* `fs::Metadata::modified`
* `fs::Metadata::accessed`
* `fs::Metadata::created`
* `sync::atomic::Atomic{Usize,Isize,Bool,Ptr}::compare_exchange`
* `sync::atomic::Atomic{Usize,Isize,Bool,Ptr}::compare_exchange_weak`
* `collections::{btree,hash}_map::{Occupied,Vacant,}Entry::key`
* `os::unix::net::{UnixStream, UnixListener, UnixDatagram, SocketAddr}`
* `SocketAddr::is_unnamed`
* `SocketAddr::as_pathname`
* `UnixStream::connect`
* `UnixStream::pair`
* `UnixStream::try_clone`
* `UnixStream::local_addr`
* `UnixStream::peer_addr`
* `UnixStream::set_read_timeout`
* `UnixStream::set_write_timeout`
* `UnixStream::read_timeout`
* `UnixStream::write_Timeout`
* `UnixStream::set_nonblocking`
* `UnixStream::take_error`
* `UnixStream::shutdown`
* Read/Write/RawFd impls for `UnixStream`
* `UnixListener::bind`
* `UnixListener::accept`
* `UnixListener::try_clone`
* `UnixListener::local_addr`
* `UnixListener::set_nonblocking`
* `UnixListener::take_error`
* `UnixListener::incoming`
* RawFd impls for `UnixListener`
* `UnixDatagram::bind`
* `UnixDatagram::unbound`
* `UnixDatagram::pair`
* `UnixDatagram::connect`
* `UnixDatagram::try_clone`
* `UnixDatagram::local_addr`
* `UnixDatagram::peer_addr`
* `UnixDatagram::recv_from`
* `UnixDatagram::recv`
* `UnixDatagram::send_to`
* `UnixDatagram::send`
* `UnixDatagram::set_read_timeout`
* `UnixDatagram::set_write_timeout`
* `UnixDatagram::read_timeout`
* `UnixDatagram::write_timeout`
* `UnixDatagram::set_nonblocking`
* `UnixDatagram::take_error`
* `UnixDatagram::shutdown`
* RawFd impls for `UnixDatagram`
* `{BTree,Hash}Map::values_mut`
* `<[_]>::binary_search_by_key`

Deprecated:

* `StaticCondvar` - this, and all other static synchronization primitives
                    below, are usable today through the lazy-static crate on
                    stable Rust today. Additionally, we'd like the non-static
                    versions to be directly usable in a static context one day,
                    so they're unlikely to be the final forms of the APIs in any
                    case.
* `CONDVAR_INIT`
* `StaticMutex`
* `MUTEX_INIT`
* `StaticRwLock`
* `RWLOCK_INIT`
* `iter::Peekable::is_empty`

Closes #27717
Closes #27720
Closes #30014
Closes #30425
Closes #30449
Closes #31190
Closes #31399
Closes #31767
Closes #32111
Closes #32281
Closes #32312
Closes #32551
Closes #33018
@bors bors merged commit cae91d7 into rust-lang:master May 26, 2016
@alexcrichton alexcrichton deleted the stabilize-1.10 branch May 26, 2016 16:22
@alexcrichton alexcrichton added beta-nominated Nominated for backporting to the compiler in the beta channel. beta-accepted Accepted for backporting to the compiler in the beta channel. labels May 26, 2016
@alexcrichton
Copy link
Member Author

Tagging beta nominated/accepted to ensure we backport

@alexcrichton alexcrichton removed the beta-nominated Nominated for backporting to the compiler in the beta channel. label Jun 20, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
beta-accepted Accepted for backporting to the compiler in the beta channel.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants