diff options
| author | Matthias Einwag <matthias.einwag@live.com> | 2019-02-12 22:46:14 -0800 |
|---|---|---|
| committer | Matthias Einwag <matthias.einwag@live.com> | 2019-02-12 22:46:14 -0800 |
| commit | 871338c3aed87cb84f02ebd7fd9b447966d5b05d (patch) | |
| tree | a2e1315d7d17d0b9f3463686ed2fbf36f3238ec4 /src/libstd | |
| parent | 1ef34a5a39641846e824b6450a705d6031002beb (diff) | |
| parent | 0f949c2fcc696d0260a99196d5e5400c59a26a54 (diff) | |
| download | rust-871338c3aed87cb84f02ebd7fd9b447966d5b05d.tar.gz rust-871338c3aed87cb84f02ebd7fd9b447966d5b05d.zip | |
Merging master
Diffstat (limited to 'src/libstd')
67 files changed, 764 insertions, 700 deletions
diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index 91c4e990e00..beecfb1aa29 100644 --- a/src/libstd/collections/hash/map.rs +++ b/src/libstd/collections/hash/map.rs @@ -370,7 +370,7 @@ const DISPLACEMENT_THRESHOLD: usize = 128; /// } /// /// impl Viking { -/// /// Create a new Viking. +/// /// Creates a new Viking. /// fn new(name: &str, country: &str) -> Viking { /// Viking { name: name.to_string(), country: country.to_string() } /// } @@ -556,7 +556,7 @@ fn pop_internal<K, V>(starting_bucket: FullBucketMut<K, V>) (retkey, retval, gap.into_table()) } -/// Perform robin hood bucket stealing at the given `bucket`. You must +/// Performs robin hood bucket stealing at the given `bucket`. You must /// also pass that bucket's displacement so we don't have to recalculate it. /// /// `hash`, `key`, and `val` are the elements to "robin hood" into the hashtable. @@ -1214,7 +1214,7 @@ impl<K, V, S> HashMap<K, V, S> self.table.size() } - /// Returns true if the map contains no elements. + /// Returns `true` if the map contains no elements. /// /// # Examples /// @@ -1332,7 +1332,7 @@ impl<K, V, S> HashMap<K, V, S> self.search(k).map(|bucket| bucket.into_refs()) } - /// Returns true if the map contains a value for the specified key. + /// Returns `true` if the map contains a value for the specified key. /// /// The key may be any borrowed form of the map's key type, but /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for @@ -1896,7 +1896,7 @@ impl<'a, K, V, S> RawEntryBuilderMut<'a, K, V, S> where S: BuildHasher, K: Eq + Hash, { - /// Create a `RawEntryMut` from the given key. + /// Creates a `RawEntryMut` from the given key. #[unstable(feature = "hash_raw_entry", issue = "56167")] pub fn from_key<Q: ?Sized>(self, k: &Q) -> RawEntryMut<'a, K, V, S> where K: Borrow<Q>, @@ -1907,7 +1907,7 @@ impl<'a, K, V, S> RawEntryBuilderMut<'a, K, V, S> self.from_key_hashed_nocheck(hasher.finish(), k) } - /// Create a `RawEntryMut` from the given key and its hash. + /// Creates a `RawEntryMut` from the given key and its hash. #[inline] #[unstable(feature = "hash_raw_entry", issue = "56167")] pub fn from_key_hashed_nocheck<Q: ?Sized>(self, hash: u64, k: &Q) -> RawEntryMut<'a, K, V, S> @@ -1939,7 +1939,7 @@ impl<'a, K, V, S> RawEntryBuilderMut<'a, K, V, S> } } } - /// Create a `RawEntryMut` from the given hash. + /// Creates a `RawEntryMut` from the given hash. #[inline] #[unstable(feature = "hash_raw_entry", issue = "56167")] pub fn from_hash<F>(self, hash: u64, is_match: F) -> RawEntryMut<'a, K, V, S> diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs index c55dd049ec6..92e63df7c68 100644 --- a/src/libstd/collections/hash/set.rs +++ b/src/libstd/collections/hash/set.rs @@ -471,7 +471,7 @@ impl<T, S> HashSet<T, S> self.map.len() } - /// Returns true if the set contains no elements. + /// Returns `true` if the set contains no elements. /// /// # Examples /// @@ -696,7 +696,7 @@ impl<T, S> HashSet<T, S> Recover::replace(&mut self.map, value) } - /// Removes a value from the set. Returns `true` if the value was + /// Removes a value from the set. Returns whether the value was /// present in the set. /// /// The value may be any borrowed form of the set's value type, but diff --git a/src/libstd/collections/hash/table.rs b/src/libstd/collections/hash/table.rs index 28beb80612c..9446a80a55c 100644 --- a/src/libstd/collections/hash/table.rs +++ b/src/libstd/collections/hash/table.rs @@ -248,11 +248,11 @@ impl<K, V, M> FullBucket<K, V, M> { pub fn into_table(self) -> M { self.table } - /// Get the raw index. + /// Gets the raw index. pub fn index(&self) -> usize { self.raw.idx } - /// Get the raw bucket. + /// Gets the raw bucket. pub fn raw(&self) -> RawBucket<K, V> { self.raw } @@ -270,7 +270,7 @@ impl<K, V, M> EmptyBucket<K, V, M> { } impl<K, V, M> Bucket<K, V, M> { - /// Get the raw index. + /// Gets the raw index. pub fn index(&self) -> usize { self.raw.idx } @@ -503,7 +503,7 @@ impl<K, V, M: Deref<Target = RawTable<K, V>>> FullBucket<K, V, M> { } } - /// Get the distance between this bucket and the 'ideal' location + /// Gets the distance between this bucket and the 'ideal' location /// as determined by the key's hash stored in it. /// /// In the cited blog posts above, this is called the "distance to @@ -839,12 +839,12 @@ impl<K, V> RawTable<K, V> { } } - /// Set the table tag + /// Sets the table tag. pub fn set_tag(&mut self, value: bool) { self.hashes.set_tag(value) } - /// Get the table tag + /// Gets the table tag. pub fn tag(&self) -> bool { self.hashes.tag() } diff --git a/src/libstd/collections/mod.rs b/src/libstd/collections/mod.rs index ef397283ca4..9ebeff48426 100644 --- a/src/libstd/collections/mod.rs +++ b/src/libstd/collections/mod.rs @@ -323,8 +323,8 @@ //! // A client of the bar. They have a blood alcohol level. //! struct Person { blood_alcohol: f32 } //! -//! // All the orders made to the bar, by client id. -//! let orders = vec![1,2,1,2,3,4,1,2,2,3,4,1,1,1]; +//! // All the orders made to the bar, by client ID. +//! let orders = vec![1, 2, 1, 2, 3, 4, 1, 2, 2, 3, 4, 1, 1, 1]; //! //! // Our clients. //! let mut blood_alcohol = BTreeMap::new(); diff --git a/src/libstd/error.rs b/src/libstd/error.rs index 50415d9aeb9..f792ff56179 100644 --- a/src/libstd/error.rs +++ b/src/libstd/error.rs @@ -195,7 +195,7 @@ pub trait Error: Debug + Display { #[stable(feature = "error_source", since = "1.30.0")] fn source(&self) -> Option<&(dyn Error + 'static)> { None } - /// Get the `TypeId` of `self` + /// Gets the `TypeId` of `self` #[doc(hidden)] #[stable(feature = "error_type_id", since = "1.34.0")] fn type_id(&self) -> TypeId where Self: 'static { @@ -564,7 +564,7 @@ impl Error for char::ParseCharError { // copied from any.rs impl dyn Error + 'static { - /// Returns true if the boxed type is the same as `T` + /// Returns `true` if the boxed type is the same as `T` #[stable(feature = "error_downcast", since = "1.3.0")] #[inline] pub fn is<T: Error + 'static>(&self) -> bool { diff --git a/src/libstd/f64.rs b/src/libstd/f64.rs index 2e0383ccef5..7fa7b807519 100644 --- a/src/libstd/f64.rs +++ b/src/libstd/f64.rs @@ -250,7 +250,7 @@ impl f64 { /// Calculates the least nonnegative remainder of `self (mod rhs)`. /// /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in - /// most cases. However, due to a floating point round-off error it can + /// most cases. However, due to a floating point round-off error it can /// result in `r == rhs.abs()`, violating the mathematical definition, if /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`. /// This result is not an element of the function's codomain, but it is the diff --git a/src/libstd/ffi/c_str.rs b/src/libstd/ffi/c_str.rs index 765452e0288..caf490a0277 100644 --- a/src/libstd/ffi/c_str.rs +++ b/src/libstd/ffi/c_str.rs @@ -377,7 +377,7 @@ impl CString { /// /// # Examples /// - /// Create a `CString`, pass ownership to an `extern` function (via raw pointer), then retake + /// Creates a `CString`, pass ownership to an `extern` function (via raw pointer), then retake /// ownership with `from_raw`: /// /// ```ignore (extern-declaration) diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs index f8176892513..7dbf15cdc90 100644 --- a/src/libstd/ffi/os_str.rs +++ b/src/libstd/ffi/os_str.rs @@ -24,7 +24,7 @@ use sys_common::{AsInner, IntoInner, FromInner}; /// /// `OsString` and [`OsStr`] bridge this gap by simultaneously representing Rust /// and platform-native string values, and in particular allowing a Rust string -/// to be converted into an "OS" string with no cost if possible. A consequence +/// to be converted into an "OS" string with no cost if possible. A consequence /// of this is that `OsString` instances are *not* `NUL` terminated; in order /// to pass to e.g., Unix system call, you should create a [`CStr`]. /// @@ -259,7 +259,7 @@ impl OsString { /// already sufficient. /// /// Note that the allocator may give the collection more space than it - /// requests. Therefore capacity can not be relied upon to be precisely + /// requests. Therefore, capacity can not be relied upon to be precisely /// minimal. Prefer reserve if future insertions are expected. /// /// # Examples diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 3538816c112..f1e8619fc8f 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -25,7 +25,7 @@ use time::SystemTime; /// /// # Examples /// -/// Create a new file and write bytes to it: +/// Creates a new file and write bytes to it: /// /// ```no_run /// use std::fs::File; @@ -222,7 +222,7 @@ fn initial_buffer_size(file: &File) -> usize { /// Read the entire contents of a file into a bytes vector. /// /// This is a convenience function for using [`File::open`] and [`read_to_end`] -/// with fewer imports and without an intermediate variable. It pre-allocates a +/// with fewer imports and without an intermediate variable. It pre-allocates a /// buffer based on the file size when available, so it is generally faster than /// reading into a vector created with `Vec::new()`. /// @@ -263,7 +263,7 @@ pub fn read<P: AsRef<Path>>(path: P) -> io::Result<Vec<u8>> { /// Read the entire contents of a file into a string. /// /// This is a convenience function for using [`File::open`] and [`read_to_string`] -/// with fewer imports and without an intermediate variable. It pre-allocates a +/// with fewer imports and without an intermediate variable. It pre-allocates a /// buffer based on the file size when available, so it is generally faster than /// reading into a string created with `String::new()`. /// @@ -488,13 +488,13 @@ impl File { self.inner.file_attr().map(Metadata) } - /// Create a new `File` instance that shares the same underlying file handle + /// Creates a new `File` instance that shares the same underlying file handle /// as the existing `File` instance. Reads, writes, and seeks will affect /// both `File` instances simultaneously. /// /// # Examples /// - /// Create two handles for a file named `foo.txt`: + /// Creates two handles for a file named `foo.txt`: /// /// ```no_run /// use std::fs::File; @@ -896,7 +896,7 @@ impl Metadata { FileType(self.0.file_type()) } - /// Returns whether this metadata is for a directory. The + /// Returns `true` if this metadata is for a directory. The /// result is mutually exclusive to the result of /// [`is_file`], and will be false for symlink metadata /// obtained from [`symlink_metadata`]. @@ -919,7 +919,7 @@ impl Metadata { #[stable(feature = "rust1", since = "1.0.0")] pub fn is_dir(&self) -> bool { self.file_type().is_dir() } - /// Returns whether this metadata is for a regular file. The + /// Returns `true` if this metadata is for a regular file. The /// result is mutually exclusive to the result of /// [`is_dir`], and will be false for symlink metadata /// obtained from [`symlink_metadata`]. @@ -1096,7 +1096,7 @@ impl AsInner<fs_imp::FileAttr> for Metadata { } impl Permissions { - /// Returns whether these permissions describe a readonly (unwritable) file. + /// Returns `true` if these permissions describe a readonly (unwritable) file. /// /// # Examples /// @@ -1152,7 +1152,7 @@ impl Permissions { } impl FileType { - /// Test whether this file type represents a directory. The + /// Tests whether this file type represents a directory. The /// result is mutually exclusive to the results of /// [`is_file`] and [`is_symlink`]; only zero or one of these /// tests may pass. @@ -1176,7 +1176,7 @@ impl FileType { #[stable(feature = "file_type", since = "1.1.0")] pub fn is_dir(&self) -> bool { self.0.is_dir() } - /// Test whether this file type represents a regular file. + /// Tests whether this file type represents a regular file. /// The result is mutually exclusive to the results of /// [`is_dir`] and [`is_symlink`]; only zero or one of these /// tests may pass. @@ -1200,7 +1200,7 @@ impl FileType { #[stable(feature = "file_type", since = "1.1.0")] pub fn is_file(&self) -> bool { self.0.is_file() } - /// Test whether this file type represents a symbolic link. + /// Tests whether this file type represents a symbolic link. /// The result is mutually exclusive to the results of /// [`is_dir`] and [`is_file`]; only zero or one of these /// tests may pass. @@ -1209,7 +1209,7 @@ impl FileType { /// with the [`fs::symlink_metadata`] function and not the /// [`fs::metadata`] function. The [`fs::metadata`] function /// follows symbolic links, so [`is_symlink`] would always - /// return false for the target file. + /// return `false` for the target file. /// /// [`Metadata`]: struct.Metadata.html /// [`fs::metadata`]: fn.metadata.html @@ -1290,7 +1290,7 @@ impl DirEntry { #[stable(feature = "rust1", since = "1.0.0")] pub fn path(&self) -> PathBuf { self.0.path() } - /// Return the metadata for the file that this entry points at. + /// Returns the metadata for the file that this entry points at. /// /// This function will not traverse symlinks if this entry points at a /// symlink. @@ -1325,7 +1325,7 @@ impl DirEntry { self.0.metadata().map(Metadata) } - /// Return the file type for the file that this entry points at. + /// Returns the file type for the file that this entry points at. /// /// This function will not traverse symlinks if this entry points at a /// symlink. @@ -2025,7 +2025,7 @@ impl DirBuilder { self } - /// Create the specified directory with the options configured in this + /// Creates the specified directory with the options configured in this /// builder. /// /// It is considered an error if the directory already exists unless diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs index 056aa7c0c42..0615cd59db4 100644 --- a/src/libstd/io/buffered.rs +++ b/src/libstd/io/buffered.rs @@ -16,9 +16,9 @@ use memchr; /// the underlying [`Read`] and maintains an in-memory buffer of the results. /// /// `BufReader` can improve the speed of programs that make *small* and -/// *repeated* read calls to the same file or network socket. It does not +/// *repeated* read calls to the same file or network socket. It does not /// help when reading very large amounts at once, or reading just one or a few -/// times. It also provides no advantage when reading from a source that is +/// times. It also provides no advantage when reading from a source that is /// already in memory, like a `Vec<u8>`. /// /// [`Read`]: ../../std/io/trait.Read.html @@ -331,9 +331,9 @@ impl<R: Seek> Seek for BufReader<R> { /// writer in large, infrequent batches. /// /// `BufWriter` can improve the speed of programs that make *small* and -/// *repeated* write calls to the same file or network socket. It does not +/// *repeated* write calls to the same file or network socket. It does not /// help when writing very large amounts at once, or writing just one or a few -/// times. It also provides no advantage when writing to a destination that is +/// times. It also provides no advantage when writing to a destination that is /// in memory, like a `Vec<u8>`. /// /// When the `BufWriter` is dropped, the contents of its buffer will be written diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 28a6fbd48cf..c0570ae60a1 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -1219,11 +1219,11 @@ pub trait Seek { #[derive(Copy, PartialEq, Eq, Clone, Debug)] #[stable(feature = "rust1", since = "1.0.0")] pub enum SeekFrom { - /// Set the offset to the provided number of bytes. + /// Sets the offset to the provided number of bytes. #[stable(feature = "rust1", since = "1.0.0")] Start(#[stable(feature = "rust1", since = "1.0.0")] u64), - /// Set the offset to the size of this object plus the specified number of + /// Sets the offset to the size of this object plus the specified number of /// bytes. /// /// It is possible to seek beyond the end of an object, but it's an error to @@ -1231,7 +1231,7 @@ pub enum SeekFrom { #[stable(feature = "rust1", since = "1.0.0")] End(#[stable(feature = "rust1", since = "1.0.0")] i64), - /// Set the offset to the current position plus the specified number of + /// Sets the offset to the current position plus the specified number of /// bytes. /// /// It is possible to seek beyond the end of an object, but it's an error to diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs index d2494693230..4068c0f9c7d 100644 --- a/src/libstd/io/stdio.rs +++ b/src/libstd/io/stdio.rs @@ -131,6 +131,11 @@ fn handle_ebadf<T>(r: io::Result<T>, default: T) -> io::Result<T> { /// /// [`io::stdin`]: fn.stdin.html /// [`BufRead`]: trait.BufRead.html +/// +/// ### Note: Windows Portability Consideration +/// When operating in a console, the Windows implementation of this stream does not support +/// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return +/// an error. #[stable(feature = "rust1", since = "1.0.0")] pub struct Stdin { inner: Arc<Mutex<BufReader<Maybe<StdinRaw>>>>, @@ -144,6 +149,11 @@ pub struct Stdin { /// [`Read`]: trait.Read.html /// [`BufRead`]: trait.BufRead.html /// [`Stdin::lock`]: struct.Stdin.html#method.lock +/// +/// ### Note: Windows Portability Consideration +/// When operating in a console, the Windows implementation of this stream does not support +/// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return +/// an error. #[stable(feature = "rust1", since = "1.0.0")] pub struct StdinLock<'a> { inner: MutexGuard<'a, BufReader<Maybe<StdinRaw>>>, @@ -157,6 +167,11 @@ pub struct StdinLock<'a> { /// /// [lock]: struct.Stdin.html#method.lock /// +/// ### Note: Windows Portability Consideration +/// When operating in a console, the Windows implementation of this stream does not support +/// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return +/// an error. +/// /// # Examples /// /// Using implicit synchronization: @@ -328,6 +343,11 @@ impl<'a> fmt::Debug for StdinLock<'a> { /// /// Created by the [`io::stdout`] method. /// +/// ### Note: Windows Portability Consideration +/// When operating in a console, the Windows implementation of this stream does not support +/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return +/// an error. +/// /// [`lock`]: #method.lock /// [`io::stdout`]: fn.stdout.html #[stable(feature = "rust1", since = "1.0.0")] @@ -343,6 +363,11 @@ pub struct Stdout { /// This handle implements the [`Write`] trait, and is constructed via /// the [`Stdout::lock`] method. /// +/// ### Note: Windows Portability Consideration +/// When operating in a console, the Windows implementation of this stream does not support +/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return +/// an error. +/// /// [`Write`]: trait.Write.html /// [`Stdout::lock`]: struct.Stdout.html#method.lock #[stable(feature = "rust1", since = "1.0.0")] @@ -358,6 +383,11 @@ pub struct StdoutLock<'a> { /// /// [Stdout::lock]: struct.Stdout.html#method.lock /// +/// ### Note: Windows Portability Consideration +/// When operating in a console, the Windows implementation of this stream does not support +/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return +/// an error. +/// /// # Examples /// /// Using implicit synchronization: @@ -476,6 +506,11 @@ impl<'a> fmt::Debug for StdoutLock<'a> { /// For more information, see the [`io::stderr`] method. /// /// [`io::stderr`]: fn.stderr.html +/// +/// ### Note: Windows Portability Consideration +/// When operating in a console, the Windows implementation of this stream does not support +/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return +/// an error. #[stable(feature = "rust1", since = "1.0.0")] pub struct Stderr { inner: Arc<ReentrantMutex<RefCell<Maybe<StderrRaw>>>>, @@ -487,6 +522,11 @@ pub struct Stderr { /// the [`Stderr::lock`] method. /// /// [`Stderr::lock`]: struct.Stderr.html#method.lock +/// +/// ### Note: Windows Portability Consideration +/// When operating in a console, the Windows implementation of this stream does not support +/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return +/// an error. #[stable(feature = "rust1", since = "1.0.0")] pub struct StderrLock<'a> { inner: ReentrantMutexGuard<'a, RefCell<Maybe<StderrRaw>>>, @@ -496,6 +536,11 @@ pub struct StderrLock<'a> { /// /// This handle is not buffered. /// +/// ### Note: Windows Portability Consideration +/// When operating in a console, the Windows implementation of this stream does not support +/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return +/// an error. +/// /// # Examples /// /// Using implicit synchronization: diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index a7ecee2d822..bef6bc92661 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -260,7 +260,7 @@ mod extern_keyword { } /// } /// /// fn generic_where<T>(x: T) -> T -/// where T: std::ops::Add<Output=T> + Copy +/// where T: std::ops::Add<Output = T> + Copy /// { /// x + x + x /// } @@ -289,7 +289,7 @@ mod fn_keyword { } /// `for` is primarily used in for-in-loops, but it has a few other pieces of syntactic uses such as /// `impl Trait for Type` (see [`impl`] for more info on that). for-in-loops, or to be more /// precise, iterator loops, are a simple syntactic sugar over an exceedingly common practice -/// within Rust, which is to loop over an iterator until that iterator returns None (or `break` +/// within Rust, which is to loop over an iterator until that iterator returns `None` (or `break` /// is called). /// /// ```rust @@ -627,7 +627,7 @@ mod loop_keyword { } /// directly accessed and modified. /// /// Tuple structs are similar to regular structs, but its fields have no names. They are used like -/// tuples, with deconstruction possible via `let TupleStruct(x, y) = foo;` syntax. For accessing +/// tuples, with deconstruction possible via `let TupleStruct(x, y) = foo;` syntax. For accessing /// individual variables, the same syntax is used as with regular tuples, namely `foo.0`, `foo.1`, /// etc, starting at zero. /// diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index 207ba9ae02f..87c8387fb6b 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -7,7 +7,7 @@ //! primitives](#primitives), [standard macros](#macros), [I/O] and //! [multithreading], among [many other things][other]. //! -//! `std` is available to all Rust crates by default. Therefore the +//! `std` is available to all Rust crates by default. Therefore, the //! standard library can be accessed in [`use`] statements through the path //! `std`, as in [`use std::env`]. //! @@ -196,9 +196,7 @@ //! [primitive types]: ../book/ch03-02-data-types.html #![stable(feature = "rust1", since = "1.0.0")] -#![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png", - html_favicon_url = "https://doc.rust-lang.org/favicon.ico", - html_root_url = "https://doc.rust-lang.org/nightly/", +#![doc(html_root_url = "https://doc.rust-lang.org/nightly/", html_playground_url = "https://play.rust-lang.org/", issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", test(no_crate_inject, attr(deny(warnings))), diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index b87257188df..dfe3079bb6c 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -11,8 +11,8 @@ /// an unrecoverable problem. /// /// This macro is the perfect way to assert conditions in example code and in -/// tests. `panic!` is closely tied with the `unwrap` method of both [`Option`] -/// and [`Result`][runwrap] enums. Both implementations call `panic!` when they are set +/// tests. `panic!` is closely tied with the `unwrap` method of both [`Option`] +/// and [`Result`][runwrap] enums. Both implementations call `panic!` when they are set /// to None or Err variants. /// /// This macro is used to inject panic into a Rust thread, causing the thread to @@ -21,7 +21,7 @@ /// is transmitted. /// /// [`Result`] enum is often a better solution for recovering from errors than -/// using the `panic!` macro. This macro should be used to avoid proceeding using +/// using the `panic!` macro. This macro should be used to avoid proceeding using /// incorrect values, such as from external sources. Detailed information about /// error handling is found in the [book]. /// @@ -53,7 +53,8 @@ /// ``` #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] -#[allow_internal_unstable] +#[cfg_attr(stage0, allow_internal_unstable)] +#[cfg_attr(not(stage0), allow_internal_unstable(__rust_unstable_column, libstd_sys_internals))] macro_rules! panic { () => ({ panic!("explicit panic") @@ -79,7 +80,7 @@ macro_rules! panic { /// necessary to use [`io::stdout().flush()`][flush] to ensure the output is emitted /// immediately. /// -/// Use `print!` only for the primary output of your program. Use +/// Use `print!` only for the primary output of your program. Use /// [`eprint!`] instead to print error and progress messages. /// /// [`println!`]: ../std/macro.println.html @@ -111,7 +112,8 @@ macro_rules! panic { /// ``` #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] -#[allow_internal_unstable] +#[cfg_attr(stage0, allow_internal_unstable)] +#[cfg_attr(not(stage0), allow_internal_unstable(print_internals))] macro_rules! print { ($($arg:tt)*) => ($crate::io::_print(format_args!($($arg)*))); } @@ -124,7 +126,7 @@ macro_rules! print { /// Use the [`format!`] syntax to write data to the standard output. /// See [`std::fmt`] for more information. /// -/// Use `println!` only for the primary output of your program. Use +/// Use `println!` only for the primary output of your program. Use /// [`eprintln!`] instead to print error and progress messages. /// /// [`format!`]: ../std/macro.format.html @@ -143,7 +145,8 @@ macro_rules! print { /// ``` #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] -#[allow_internal_unstable] +#[cfg_attr(stage0, allow_internal_unstable)] +#[cfg_attr(not(stage0), allow_internal_unstable(print_internals, format_args_nl))] macro_rules! println { () => (print!("\n")); ($($arg:tt)*) => ({ @@ -154,10 +157,10 @@ macro_rules! println { /// Macro for printing to the standard error. /// /// Equivalent to the [`print!`] macro, except that output goes to -/// [`io::stderr`] instead of `io::stdout`. See [`print!`] for +/// [`io::stderr`] instead of `io::stdout`. See [`print!`] for /// example usage. /// -/// Use `eprint!` only for error and progress messages. Use `print!` +/// Use `eprint!` only for error and progress messages. Use `print!` /// instead for the primary output of your program. /// /// [`io::stderr`]: ../std/io/struct.Stderr.html @@ -174,7 +177,8 @@ macro_rules! println { /// ``` #[macro_export] #[stable(feature = "eprint", since = "1.19.0")] -#[allow_internal_unstable] +#[cfg_attr(stage0, allow_internal_unstable)] +#[cfg_attr(not(stage0), allow_internal_unstable(print_internals))] macro_rules! eprint { ($($arg:tt)*) => ($crate::io::_eprint(format_args!($($arg)*))); } @@ -182,10 +186,10 @@ macro_rules! eprint { /// Macro for printing to the standard error, with a newline. /// /// Equivalent to the [`println!`] macro, except that output goes to -/// [`io::stderr`] instead of `io::stdout`. See [`println!`] for +/// [`io::stderr`] instead of `io::stdout`. See [`println!`] for /// example usage. /// -/// Use `eprintln!` only for error and progress messages. Use `println!` +/// Use `eprintln!` only for error and progress messages. Use `println!` /// instead for the primary output of your program. /// /// [`io::stderr`]: ../std/io/struct.Stderr.html @@ -202,7 +206,8 @@ macro_rules! eprint { /// ``` #[macro_export] #[stable(feature = "eprint", since = "1.19.0")] -#[allow_internal_unstable] +#[cfg_attr(stage0, allow_internal_unstable)] +#[cfg_attr(not(stage0), allow_internal_unstable(print_internals, format_args_nl))] macro_rules! eprintln { () => (eprint!("\n")); ($($arg:tt)*) => ({ @@ -325,7 +330,8 @@ macro_rules! dbg { /// A macro to await on an async call. #[macro_export] #[unstable(feature = "await_macro", issue = "50547")] -#[allow_internal_unstable] +#[cfg_attr(stage0, allow_internal_unstable)] +#[cfg_attr(not(stage0), allow_internal_unstable(gen_future, generators))] #[allow_internal_unsafe] macro_rules! await { ($e:expr) => { { @@ -462,16 +468,16 @@ mod builtin { /// The core macro for formatted string creation & output. /// /// This macro functions by taking a formatting string literal containing - /// `{}` for each additional argument passed. `format_args!` prepares the + /// `{}` for each additional argument passed. `format_args!` prepares the /// additional parameters to ensure the output can be interpreted as a string - /// and canonicalizes the arguments into a single type. Any value that implements + /// and canonicalizes the arguments into a single type. Any value that implements /// the [`Display`] trait can be passed to `format_args!`, as can any /// [`Debug`] implementation be passed to a `{:?}` within the formatting string. /// /// This macro produces a value of type [`fmt::Arguments`]. This value can be /// passed to the macros within [`std::fmt`] for performing useful redirection. /// All other formatting macros ([`format!`], [`write!`], [`println!`], etc) are - /// proxied through this one. `format_args!`, unlike its derived macros, avoids + /// proxied through this one. `format_args!`, unlike its derived macros, avoids /// heap allocations. /// /// You can use the [`fmt::Arguments`] value that `format_args!` returns @@ -554,7 +560,7 @@ mod builtin { /// If the named environment variable is present at compile time, this will /// expand into an expression of type `Option<&'static str>` whose value is /// `Some` of the value of the environment variable. If the environment - /// variable is not present, then this will expand to `None`. See + /// variable is not present, then this will expand to `None`. See /// [`Option<T>`][option] for more information on this type. /// /// A compile time error is never emitted when using this macro regardless @@ -904,7 +910,7 @@ mod builtin { /// # Custom Messages /// /// This macro has a second form, where a custom panic message can - /// be provided with or without arguments for formatting. See [`std::fmt`] + /// be provided with or without arguments for formatting. See [`std::fmt`] /// for syntax for this form. /// /// [`panic!`]: macro.panic.html diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index 8ace1127658..654ad64d97b 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -510,7 +510,7 @@ impl SocketAddrV6 { self.inner.sin6_scope_id } - /// Change the scope ID associated with this socket address. + /// Changes the scope ID associated with this socket address. /// /// See the [`scope_id`] method's documentation for more details. /// @@ -671,7 +671,7 @@ impl hash::Hash for SocketAddrV6 { /// [`SocketAddr`] values. /// /// This trait is used for generic address resolution when constructing network -/// objects. By default it is implemented for the following types: +/// objects. By default it is implemented for the following types: /// /// * [`SocketAddr`]: [`to_socket_addrs`] is the identity function. /// diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index f45cd8b8c10..d19cc482c15 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -392,8 +392,7 @@ impl Ipv4Addr { /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn octets(&self) -> [u8; 4] { - let bits = u32::from_be(self.inner.s_addr); - [(bits >> 24) as u8, (bits >> 16) as u8, (bits >> 8) as u8, bits as u8] + self.inner.s_addr.to_ne_bytes() } /// Returns [`true`] for the special 'unspecified' address (0.0.0.0). @@ -773,7 +772,7 @@ impl FromInner<c::in_addr> for Ipv4Addr { #[stable(feature = "ip_u32", since = "1.1.0")] impl From<Ipv4Addr> for u32 { - /// Convert an `Ipv4Addr` into a host byte order `u32`. + /// Converts an `Ipv4Addr` into a host byte order `u32`. /// /// # Examples /// @@ -791,7 +790,7 @@ impl From<Ipv4Addr> for u32 { #[stable(feature = "ip_u32", since = "1.1.0")] impl From<u32> for Ipv4Addr { - /// Convert a host byte order `u32` into an `Ipv4Addr`. + /// Converts a host byte order `u32` into an `Ipv4Addr`. /// /// # Examples /// @@ -823,7 +822,7 @@ impl From<[u8; 4]> for Ipv4Addr { #[stable(feature = "ip_from_slice", since = "1.17.0")] impl From<[u8; 4]> for IpAddr { - /// Create an `IpAddr::V4` from a four element byte array. + /// Creates an `IpAddr::V4` from a four element byte array. /// /// # Examples /// @@ -1420,7 +1419,7 @@ impl From<[u16; 8]> for Ipv6Addr { #[stable(feature = "ip_from_slice", since = "1.17.0")] impl From<[u8; 16]> for IpAddr { - /// Create an `IpAddr::V6` from a sixteen element byte array. + /// Creates an `IpAddr::V6` from a sixteen element byte array. /// /// # Examples /// @@ -1448,7 +1447,7 @@ impl From<[u8; 16]> for IpAddr { #[stable(feature = "ip_from_slice", since = "1.17.0")] impl From<[u16; 8]> for IpAddr { - /// Create an `IpAddr::V6` from an eight element 16-bit array. + /// Creates an `IpAddr::V6` from an eight element 16-bit array. /// /// # Examples /// diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index 86ecb10edf2..c4b0cd0f17c 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -497,7 +497,7 @@ impl TcpStream { self.0.ttl() } - /// Get the value of the `SO_ERROR` option on this socket. + /// Gets the value of the `SO_ERROR` option on this socket. /// /// This will retrieve the stored error in the underlying socket, clearing /// the field in the process. This can be useful for checking errors between @@ -636,7 +636,7 @@ impl TcpListener { /// /// # Examples /// - /// Create a TCP listener bound to `127.0.0.1:80`: + /// Creates a TCP listener bound to `127.0.0.1:80`: /// /// ```no_run /// use std::net::TcpListener; @@ -644,7 +644,7 @@ impl TcpListener { /// let listener = TcpListener::bind("127.0.0.1:80").unwrap(); /// ``` /// - /// Create a TCP listener bound to `127.0.0.1:80`. If that fails, create a + /// Creates a TCP listener bound to `127.0.0.1:80`. If that fails, create a /// TCP listener bound to `127.0.0.1:443`: /// /// ```no_run @@ -811,7 +811,7 @@ impl TcpListener { self.0.only_v6() } - /// Get the value of the `SO_ERROR` option on this socket. + /// Gets the value of the `SO_ERROR` option on this socket. /// /// This will retrieve the stored error in the underlying socket, clearing /// the field in the process. This can be useful for checking errors between diff --git a/src/libstd/net/udp.rs b/src/libstd/net/udp.rs index 83459946ba6..d49871ce7bd 100644 --- a/src/libstd/net/udp.rs +++ b/src/libstd/net/udp.rs @@ -69,7 +69,7 @@ impl UdpSocket { /// /// # Examples /// - /// Create a UDP socket bound to `127.0.0.1:3400`: + /// Creates a UDP socket bound to `127.0.0.1:3400`: /// /// ```no_run /// use std::net::UdpSocket; @@ -77,7 +77,7 @@ impl UdpSocket { /// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address"); /// ``` /// - /// Create a UDP socket bound to `127.0.0.1:3400`. If the socket cannot be + /// Creates a UDP socket bound to `127.0.0.1:3400`. If the socket cannot be /// bound to that address, create a UDP socket bound to `127.0.0.1:3401`: /// /// ```no_run @@ -158,7 +158,7 @@ impl UdpSocket { /// This will return an error when the IP version of the local socket /// does not match that returned from [`ToSocketAddrs`]. /// - /// See <https://github.com/rust-lang/rust/issues/34202> for more details. + /// See issue #34202 for more details. /// /// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html /// @@ -590,7 +590,7 @@ impl UdpSocket { self.0.leave_multicast_v6(multiaddr, interface) } - /// Get the value of the `SO_ERROR` option on this socket. + /// Gets the value of the `SO_ERROR` option on this socket. /// /// This will retrieve the stored error in the underlying socket, clearing /// the field in the process. This can be useful for checking errors between @@ -627,7 +627,7 @@ impl UdpSocket { /// /// # Examples /// - /// Create a UDP socket bound to `127.0.0.1:3400` and connect the socket to + /// Creates a UDP socket bound to `127.0.0.1:3400` and connect the socket to /// `127.0.0.1:8080`: /// /// ```no_run @@ -756,7 +756,7 @@ impl UdpSocket { /// /// # Examples /// - /// Create a UDP socket bound to `127.0.0.1:7878` and read bytes in + /// Creates a UDP socket bound to `127.0.0.1:7878` and read bytes in /// nonblocking mode: /// /// ```no_run diff --git a/src/libstd/os/fortanix_sgx/mod.rs b/src/libstd/os/fortanix_sgx/mod.rs index c6106b9f827..bd6f4b4465b 100644 --- a/src/libstd/os/fortanix_sgx/mod.rs +++ b/src/libstd/os/fortanix_sgx/mod.rs @@ -16,7 +16,7 @@ pub mod usercalls { /// Primitives for allocating memory in userspace as well as copying data /// to and from user memory. pub mod alloc { - pub use sys::abi::usercalls::alloc; + pub use sys::abi::usercalls::alloc::*; } /// Lowest-level interfaces to usercalls and usercall ABI type definitions. diff --git a/src/libstd/path.rs b/src/libstd/path.rs index 5c7bff70a0d..0f1d627fa1e 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -2393,7 +2393,7 @@ impl Path { fs::read_dir(self) } - /// Returns whether the path points at an existing entity. + /// Returns `true` if the path points at an existing entity. /// /// This function will traverse symbolic links to query information about the /// destination file. In case of broken symbolic links this will return `false`. @@ -2419,7 +2419,7 @@ impl Path { fs::metadata(self).is_ok() } - /// Returns whether the path exists on disk and is pointing at a regular file. + /// Returns `true` if the path exists on disk and is pointing at a regular file. /// /// This function will traverse symbolic links to query information about the /// destination file. In case of broken symbolic links this will return `false`. @@ -2448,7 +2448,7 @@ impl Path { fs::metadata(self).map(|m| m.is_file()).unwrap_or(false) } - /// Returns whether the path exists on disk and is pointing at a directory. + /// Returns `true` if the path exists on disk and is pointing at a directory. /// /// This function will traverse symbolic links to query information about the /// destination file. In case of broken symbolic links this will return `false`. diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs index c2751508ce0..6bb7f28efeb 100644 --- a/src/libstd/primitive_docs.rs +++ b/src/libstd/primitive_docs.rs @@ -126,7 +126,7 @@ mod prim_bool { } /// /// ```ignore (string-from-str-error-type-is-not-never-yet) /// #[feature(exhaustive_patterns)] -/// // NOTE: This does not work today! +/// // NOTE: this does not work today! /// let Ok(s) = String::from_str("hello"); /// ``` /// @@ -1062,7 +1062,7 @@ mod prim_ref { } /// On top of that, function pointers can vary based on what ABI they use. This is achieved by /// adding the `extern` keyword to the type name, followed by the ABI in question. For example, /// `fn()` is different from `extern "C" fn()`, which itself is different from `extern "stdcall" -/// fn()`, and so on for the various ABIs that Rust supports. Non-`extern` functions have an ABI +/// fn()`, and so on for the various ABIs that Rust supports. Non-`extern` functions have an ABI /// of `"Rust"`, and `extern` functions without an explicit ABI have an ABI of `"C"`. For more /// information, see [the nomicon's section on foreign calling conventions][nomicon-abi]. /// diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 1263ef82e48..a2ef85016d8 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -427,7 +427,7 @@ impl Command { /// The search path to be used may be controlled by setting the /// `PATH` environment variable on the Command, /// but this has some implementation limitations on Windows - /// (see <https://github.com/rust-lang/rust/issues/37519>). + /// (see issue #37519). /// /// # Examples /// @@ -445,7 +445,7 @@ impl Command { Command { inner: imp::Command::new(program.as_ref()) } } - /// Add an argument to pass to the program. + /// Adds an argument to pass to the program. /// /// Only one argument can be passed per use. So instead of: /// @@ -487,7 +487,7 @@ impl Command { self } - /// Add multiple arguments to pass to the program. + /// Adds multiple arguments to pass to the program. /// /// To pass a single argument see [`arg`]. /// @@ -540,7 +540,7 @@ impl Command { self } - /// Add or update multiple environment variable mappings. + /// Adds or updates multiple environment variable mappings. /// /// # Examples /// @@ -1287,7 +1287,7 @@ impl Child { /// /// let mut command = Command::new("ls"); /// if let Ok(child) = command.spawn() { - /// println!("Child's id is {}", child.id()); + /// println!("Child's ID is {}", child.id()); /// } else { /// println!("ls command didn't start"); /// } @@ -1332,7 +1332,7 @@ impl Child { /// /// This function will not block the calling thread and will only /// check to see if the child process has exited or not. If the child has - /// exited then on Unix the process id is reaped. This function is + /// exited then on Unix the process ID is reaped. This function is /// guaranteed to repeatedly return a successful exit status so long as the /// child has already exited. /// @@ -1979,7 +1979,7 @@ mod tests { } } - /// Test that process creation flags work by debugging a process. + /// Tests that process creation flags work by debugging a process. /// Other creation flags make it hard or impossible to detect /// behavioral changes in the process. #[test] diff --git a/src/libstd/sync/barrier.rs b/src/libstd/sync/barrier.rs index f248c721e9a..bc2e14d436a 100644 --- a/src/libstd/sync/barrier.rs +++ b/src/libstd/sync/barrier.rs @@ -159,7 +159,7 @@ impl fmt::Debug for BarrierWaitResult { } impl BarrierWaitResult { - /// Returns whether this thread from [`wait`] is the "leader thread". + /// Returns `true` if this thread from [`wait`] is the "leader thread". /// /// Only one thread will have `true` returned from their result, all other /// threads will have `false` returned. diff --git a/src/libstd/sync/condvar.rs b/src/libstd/sync/condvar.rs index 76887379106..036aff090ea 100644 --- a/src/libstd/sync/condvar.rs +++ b/src/libstd/sync/condvar.rs @@ -17,7 +17,7 @@ use time::{Duration, Instant}; pub struct WaitTimeoutResult(bool); impl WaitTimeoutResult { - /// Returns whether the wait was known to have timed out. + /// Returns `true` if the wait was known to have timed out. /// /// # Examples /// @@ -343,13 +343,13 @@ impl Condvar { /// /// Note that the best effort is made to ensure that the time waited is /// measured with a monotonic clock, and not affected by the changes made to - /// the system time. This function is susceptible to spurious wakeups. + /// the system time. This function is susceptible to spurious wakeups. /// Condition variables normally have a boolean predicate associated with /// them, and the predicate must always be checked each time this function - /// returns to protect against spurious wakeups. Additionally, it is + /// returns to protect against spurious wakeups. Additionally, it is /// typically desirable for the time-out to not exceed some duration in /// spite of spurious wakes, thus the sleep-duration is decremented by the - /// amount slept. Alternatively, use the `wait_timeout_until` method + /// amount slept. Alternatively, use the `wait_timeout_until` method /// to wait until a condition is met with a total time-out regardless /// of spurious wakes. /// @@ -413,7 +413,7 @@ impl Condvar { } /// Waits on this condition variable for a notification, timing out after a - /// specified duration. Spurious wakes will not cause this function to + /// specified duration. Spurious wakes will not cause this function to /// return. /// /// The semantics of this function are equivalent to [`wait_until`] except diff --git a/src/libstd/sync/mpsc/blocking.rs b/src/libstd/sync/mpsc/blocking.rs index ae5a18adbb3..eaf09a16756 100644 --- a/src/libstd/sync/mpsc/blocking.rs +++ b/src/libstd/sync/mpsc/blocking.rs @@ -50,14 +50,14 @@ impl SignalToken { wake } - /// Convert to an unsafe usize value. Useful for storing in a pipe's state + /// Converts to an unsafe usize value. Useful for storing in a pipe's state /// flag. #[inline] pub unsafe fn cast_to_usize(self) -> usize { mem::transmute(self.inner) } - /// Convert from an unsafe usize value. Useful for retrieving a pipe's state + /// Converts from an unsafe usize value. Useful for retrieving a pipe's state /// flag. #[inline] pub unsafe fn cast_from_usize(signal_ptr: usize) -> SignalToken { @@ -72,7 +72,7 @@ impl WaitToken { } } - /// Returns true if we wake up normally, false otherwise. + /// Returns `true` if we wake up normally. pub fn wait_max_until(self, end: Instant) -> bool { while !self.inner.woken.load(Ordering::SeqCst) { let now = Instant::now(); diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs index 446c164965d..5273345c6b4 100644 --- a/src/libstd/sync/mpsc/mod.rs +++ b/src/libstd/sync/mpsc/mod.rs @@ -279,6 +279,9 @@ use self::select::StartResult; use self::select::StartResult::*; use self::blocking::SignalToken; +#[cfg(all(test, not(target_os = "emscripten")))] +mod select_tests; + mod blocking; mod oneshot; mod select; @@ -789,7 +792,7 @@ impl<T> Sender<T> { /// where the corresponding receiver has already been deallocated. Note /// that a return value of [`Err`] means that the data will never be /// received, but a return value of [`Ok`] does *not* mean that the data - /// will be received. It is possible for the corresponding receiver to + /// will be received. It is possible for the corresponding receiver to /// hang up immediately after this function returns [`Ok`]. /// /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err diff --git a/src/libstd/sync/mpsc/select.rs b/src/libstd/sync/mpsc/select.rs index 8f41680a818..8f6f9818d5c 100644 --- a/src/libstd/sync/mpsc/select.rs +++ b/src/libstd/sync/mpsc/select.rs @@ -72,11 +72,11 @@ struct SelectInner { impl !marker::Send for Select {} /// A handle to a receiver which is currently a member of a `Select` set of -/// receivers. This handle is used to keep the receiver in the set as well as +/// receivers. This handle is used to keep the receiver in the set as well as /// interact with the underlying receiver. pub struct Handle<'rx, T:Send+'rx> { /// The ID of this handle, used to compare against the return value of - /// `Select::wait()` + /// `Select::wait()`. id: usize, selector: *mut SelectInner, next: *mut Handle<'static, ()>, @@ -148,7 +148,7 @@ impl Select { } /// Waits for an event on this receiver set. The returned value is *not* an - /// index, but rather an id. This id can be queried against any active + /// index, but rather an ID. This ID can be queried against any active /// `Handle` structures (each one has an `id` method). The handle with /// the matching `id` will have some sort of event available on it. The /// event could either be that data is available or the corresponding @@ -158,7 +158,7 @@ impl Select { } /// Helper method for skipping the preflight checks during testing - fn wait2(&self, do_preflight_checks: bool) -> usize { + pub(super) fn wait2(&self, do_preflight_checks: bool) -> usize { // Note that this is currently an inefficient implementation. We in // theory have knowledge about all receivers in the set ahead of time, // so this method shouldn't really have to iterate over all of them yet @@ -251,7 +251,7 @@ impl Select { } impl<'rx, T: Send> Handle<'rx, T> { - /// Retrieves the id of this handle. + /// Retrieves the ID of this handle. #[inline] pub fn id(&self) -> usize { self.id } @@ -352,417 +352,3 @@ impl<'rx, T:Send+'rx> fmt::Debug for Handle<'rx, T> { f.debug_struct("Handle").finish() } } - -#[allow(unused_imports)] -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests { - use thread; - use sync::mpsc::*; - - // Don't use the libstd version so we can pull in the right Select structure - // (std::comm points at the wrong one) - macro_rules! select { - ( - $($name:pat = $rx:ident.$meth:ident() => $code:expr),+ - ) => ({ - let sel = Select::new(); - $( let mut $rx = sel.handle(&$rx); )+ - unsafe { - $( $rx.add(); )+ - } - let ret = sel.wait(); - $( if ret == $rx.id() { let $name = $rx.$meth(); $code } else )+ - { unreachable!() } - }) - } - - #[test] - fn smoke() { - let (tx1, rx1) = channel::<i32>(); - let (tx2, rx2) = channel::<i32>(); - tx1.send(1).unwrap(); - select! { - foo = rx1.recv() => { assert_eq!(foo.unwrap(), 1); }, - _bar = rx2.recv() => { panic!() } - } - tx2.send(2).unwrap(); - select! { - _foo = rx1.recv() => { panic!() }, - bar = rx2.recv() => { assert_eq!(bar.unwrap(), 2) } - } - drop(tx1); - select! { - foo = rx1.recv() => { assert!(foo.is_err()); }, - _bar = rx2.recv() => { panic!() } - } - drop(tx2); - select! { - bar = rx2.recv() => { assert!(bar.is_err()); } - } - } - - #[test] - fn smoke2() { - let (_tx1, rx1) = channel::<i32>(); - let (_tx2, rx2) = channel::<i32>(); - let (_tx3, rx3) = channel::<i32>(); - let (_tx4, rx4) = channel::<i32>(); - let (tx5, rx5) = channel::<i32>(); - tx5.send(4).unwrap(); - select! { - _foo = rx1.recv() => { panic!("1") }, - _foo = rx2.recv() => { panic!("2") }, - _foo = rx3.recv() => { panic!("3") }, - _foo = rx4.recv() => { panic!("4") }, - foo = rx5.recv() => { assert_eq!(foo.unwrap(), 4); } - } - } - - #[test] - fn closed() { - let (_tx1, rx1) = channel::<i32>(); - let (tx2, rx2) = channel::<i32>(); - drop(tx2); - - select! { - _a1 = rx1.recv() => { panic!() }, - a2 = rx2.recv() => { assert!(a2.is_err()); } - } - } - - #[test] - fn unblocks() { - let (tx1, rx1) = channel::<i32>(); - let (_tx2, rx2) = channel::<i32>(); - let (tx3, rx3) = channel::<i32>(); - - let _t = thread::spawn(move|| { - for _ in 0..20 { thread::yield_now(); } - tx1.send(1).unwrap(); - rx3.recv().unwrap(); - for _ in 0..20 { thread::yield_now(); } - }); - - select! { - a = rx1.recv() => { assert_eq!(a.unwrap(), 1); }, - _b = rx2.recv() => { panic!() } - } - tx3.send(1).unwrap(); - select! { - a = rx1.recv() => { assert!(a.is_err()) }, - _b = rx2.recv() => { panic!() } - } - } - - #[test] - fn both_ready() { - let (tx1, rx1) = channel::<i32>(); - let (tx2, rx2) = channel::<i32>(); - let (tx3, rx3) = channel::<()>(); - - let _t = thread::spawn(move|| { - for _ in 0..20 { thread::yield_now(); } - tx1.send(1).unwrap(); - tx2.send(2).unwrap(); - rx3.recv().unwrap(); - }); - - select! { - a = rx1.recv() => { assert_eq!(a.unwrap(), 1); }, - a = rx2.recv() => { assert_eq!(a.unwrap(), 2); } - } - select! { - a = rx1.recv() => { assert_eq!(a.unwrap(), 1); }, - a = rx2.recv() => { assert_eq!(a.unwrap(), 2); } - } - assert_eq!(rx1.try_recv(), Err(TryRecvError::Empty)); - assert_eq!(rx2.try_recv(), Err(TryRecvError::Empty)); - tx3.send(()).unwrap(); - } - - #[test] - fn stress() { - const AMT: i32 = 10000; - let (tx1, rx1) = channel::<i32>(); - let (tx2, rx2) = channel::<i32>(); - let (tx3, rx3) = channel::<()>(); - - let _t = thread::spawn(move|| { - for i in 0..AMT { - if i % 2 == 0 { - tx1.send(i).unwrap(); - } else { - tx2.send(i).unwrap(); - } - rx3.recv().unwrap(); - } - }); - - for i in 0..AMT { - select! { - i1 = rx1.recv() => { assert!(i % 2 == 0 && i == i1.unwrap()); }, - i2 = rx2.recv() => { assert!(i % 2 == 1 && i == i2.unwrap()); } - } - tx3.send(()).unwrap(); - } - } - - #[allow(unused_must_use)] - #[test] - fn cloning() { - let (tx1, rx1) = channel::<i32>(); - let (_tx2, rx2) = channel::<i32>(); - let (tx3, rx3) = channel::<()>(); - - let _t = thread::spawn(move|| { - rx3.recv().unwrap(); - tx1.clone(); - assert_eq!(rx3.try_recv(), Err(TryRecvError::Empty)); - tx1.send(2).unwrap(); - rx3.recv().unwrap(); - }); - - tx3.send(()).unwrap(); - select! { - _i1 = rx1.recv() => {}, - _i2 = rx2.recv() => panic!() - } - tx3.send(()).unwrap(); - } - - #[allow(unused_must_use)] - #[test] - fn cloning2() { - let (tx1, rx1) = channel::<i32>(); - let (_tx2, rx2) = channel::<i32>(); - let (tx3, rx3) = channel::<()>(); - - let _t = thread::spawn(move|| { - rx3.recv().unwrap(); - tx1.clone(); - assert_eq!(rx3.try_recv(), Err(TryRecvError::Empty)); - tx1.send(2).unwrap(); - rx3.recv().unwrap(); - }); - - tx3.send(()).unwrap(); - select! { - _i1 = rx1.recv() => {}, - _i2 = rx2.recv() => panic!() - } - tx3.send(()).unwrap(); - } - - #[test] - fn cloning3() { - let (tx1, rx1) = channel::<()>(); - let (tx2, rx2) = channel::<()>(); - let (tx3, rx3) = channel::<()>(); - let _t = thread::spawn(move|| { - let s = Select::new(); - let mut h1 = s.handle(&rx1); - let mut h2 = s.handle(&rx2); - unsafe { h2.add(); } - unsafe { h1.add(); } - assert_eq!(s.wait(), h2.id); - tx3.send(()).unwrap(); - }); - - for _ in 0..1000 { thread::yield_now(); } - drop(tx1.clone()); - tx2.send(()).unwrap(); - rx3.recv().unwrap(); - } - - #[test] - fn preflight1() { - let (tx, rx) = channel(); - tx.send(()).unwrap(); - select! { - _n = rx.recv() => {} - } - } - - #[test] - fn preflight2() { - let (tx, rx) = channel(); - tx.send(()).unwrap(); - tx.send(()).unwrap(); - select! { - _n = rx.recv() => {} - } - } - - #[test] - fn preflight3() { - let (tx, rx) = channel(); - drop(tx.clone()); - tx.send(()).unwrap(); - select! { - _n = rx.recv() => {} - } - } - - #[test] - fn preflight4() { - let (tx, rx) = channel(); - tx.send(()).unwrap(); - let s = Select::new(); - let mut h = s.handle(&rx); - unsafe { h.add(); } - assert_eq!(s.wait2(false), h.id); - } - - #[test] - fn preflight5() { - let (tx, rx) = channel(); - tx.send(()).unwrap(); - tx.send(()).unwrap(); - let s = Select::new(); - let mut h = s.handle(&rx); - unsafe { h.add(); } - assert_eq!(s.wait2(false), h.id); - } - - #[test] - fn preflight6() { - let (tx, rx) = channel(); - drop(tx.clone()); - tx.send(()).unwrap(); - let s = Select::new(); - let mut h = s.handle(&rx); - unsafe { h.add(); } - assert_eq!(s.wait2(false), h.id); - } - - #[test] - fn preflight7() { - let (tx, rx) = channel::<()>(); - drop(tx); - let s = Select::new(); - let mut h = s.handle(&rx); - unsafe { h.add(); } - assert_eq!(s.wait2(false), h.id); - } - - #[test] - fn preflight8() { - let (tx, rx) = channel(); - tx.send(()).unwrap(); - drop(tx); - rx.recv().unwrap(); - let s = Select::new(); - let mut h = s.handle(&rx); - unsafe { h.add(); } - assert_eq!(s.wait2(false), h.id); - } - - #[test] - fn preflight9() { - let (tx, rx) = channel(); - drop(tx.clone()); - tx.send(()).unwrap(); - drop(tx); - rx.recv().unwrap(); - let s = Select::new(); - let mut h = s.handle(&rx); - unsafe { h.add(); } - assert_eq!(s.wait2(false), h.id); - } - - #[test] - fn oneshot_data_waiting() { - let (tx1, rx1) = channel(); - let (tx2, rx2) = channel(); - let _t = thread::spawn(move|| { - select! { - _n = rx1.recv() => {} - } - tx2.send(()).unwrap(); - }); - - for _ in 0..100 { thread::yield_now() } - tx1.send(()).unwrap(); - rx2.recv().unwrap(); - } - - #[test] - fn stream_data_waiting() { - let (tx1, rx1) = channel(); - let (tx2, rx2) = channel(); - tx1.send(()).unwrap(); - tx1.send(()).unwrap(); - rx1.recv().unwrap(); - rx1.recv().unwrap(); - let _t = thread::spawn(move|| { - select! { - _n = rx1.recv() => {} - } - tx2.send(()).unwrap(); - }); - - for _ in 0..100 { thread::yield_now() } - tx1.send(()).unwrap(); - rx2.recv().unwrap(); - } - - #[test] - fn shared_data_waiting() { - let (tx1, rx1) = channel(); - let (tx2, rx2) = channel(); - drop(tx1.clone()); - tx1.send(()).unwrap(); - rx1.recv().unwrap(); - let _t = thread::spawn(move|| { - select! { - _n = rx1.recv() => {} - } - tx2.send(()).unwrap(); - }); - - for _ in 0..100 { thread::yield_now() } - tx1.send(()).unwrap(); - rx2.recv().unwrap(); - } - - #[test] - fn sync1() { - let (tx, rx) = sync_channel::<i32>(1); - tx.send(1).unwrap(); - select! { - n = rx.recv() => { assert_eq!(n.unwrap(), 1); } - } - } - - #[test] - fn sync2() { - let (tx, rx) = sync_channel::<i32>(0); - let _t = thread::spawn(move|| { - for _ in 0..100 { thread::yield_now() } - tx.send(1).unwrap(); - }); - select! { - n = rx.recv() => { assert_eq!(n.unwrap(), 1); } - } - } - - #[test] - fn sync3() { - let (tx1, rx1) = sync_channel::<i32>(0); - let (tx2, rx2): (Sender<i32>, Receiver<i32>) = channel(); - let _t = thread::spawn(move|| { tx1.send(1).unwrap(); }); - let _t = thread::spawn(move|| { tx2.send(2).unwrap(); }); - select! { - n = rx1.recv() => { - let n = n.unwrap(); - assert_eq!(n, 1); - assert_eq!(rx2.recv().unwrap(), 2); - }, - n = rx2.recv() => { - let n = n.unwrap(); - assert_eq!(n, 2); - assert_eq!(rx1.recv().unwrap(), 1); - } - } - } -} diff --git a/src/libstd/sync/mpsc/select_tests.rs b/src/libstd/sync/mpsc/select_tests.rs new file mode 100644 index 00000000000..be048511caa --- /dev/null +++ b/src/libstd/sync/mpsc/select_tests.rs @@ -0,0 +1,413 @@ +#![allow(unused_imports)] + +/// This file exists to hack around https://github.com/rust-lang/rust/issues/47238 + +use thread; +use sync::mpsc::*; + +// Don't use the libstd version so we can pull in the right Select structure +// (std::comm points at the wrong one) +macro_rules! select { + ( + $($name:pat = $rx:ident.$meth:ident() => $code:expr),+ + ) => ({ + let sel = Select::new(); + $( let mut $rx = sel.handle(&$rx); )+ + unsafe { + $( $rx.add(); )+ + } + let ret = sel.wait(); + $( if ret == $rx.id() { let $name = $rx.$meth(); $code } else )+ + { unreachable!() } + }) +} + +#[test] +fn smoke() { + let (tx1, rx1) = channel::<i32>(); + let (tx2, rx2) = channel::<i32>(); + tx1.send(1).unwrap(); + select! { + foo = rx1.recv() => { assert_eq!(foo.unwrap(), 1); }, + _bar = rx2.recv() => { panic!() } + } + tx2.send(2).unwrap(); + select! { + _foo = rx1.recv() => { panic!() }, + bar = rx2.recv() => { assert_eq!(bar.unwrap(), 2) } + } + drop(tx1); + select! { + foo = rx1.recv() => { assert!(foo.is_err()); }, + _bar = rx2.recv() => { panic!() } + } + drop(tx2); + select! { + bar = rx2.recv() => { assert!(bar.is_err()); } + } +} + +#[test] +fn smoke2() { + let (_tx1, rx1) = channel::<i32>(); + let (_tx2, rx2) = channel::<i32>(); + let (_tx3, rx3) = channel::<i32>(); + let (_tx4, rx4) = channel::<i32>(); + let (tx5, rx5) = channel::<i32>(); + tx5.send(4).unwrap(); + select! { + _foo = rx1.recv() => { panic!("1") }, + _foo = rx2.recv() => { panic!("2") }, + _foo = rx3.recv() => { panic!("3") }, + _foo = rx4.recv() => { panic!("4") }, + foo = rx5.recv() => { assert_eq!(foo.unwrap(), 4); } + } +} + +#[test] +fn closed() { + let (_tx1, rx1) = channel::<i32>(); + let (tx2, rx2) = channel::<i32>(); + drop(tx2); + + select! { + _a1 = rx1.recv() => { panic!() }, + a2 = rx2.recv() => { assert!(a2.is_err()); } + } +} + +#[test] +fn unblocks() { + let (tx1, rx1) = channel::<i32>(); + let (_tx2, rx2) = channel::<i32>(); + let (tx3, rx3) = channel::<i32>(); + + let _t = thread::spawn(move|| { + for _ in 0..20 { thread::yield_now(); } + tx1.send(1).unwrap(); + rx3.recv().unwrap(); + for _ in 0..20 { thread::yield_now(); } + }); + + select! { + a = rx1.recv() => { assert_eq!(a.unwrap(), 1); }, + _b = rx2.recv() => { panic!() } + } + tx3.send(1).unwrap(); + select! { + a = rx1.recv() => { assert!(a.is_err()) }, + _b = rx2.recv() => { panic!() } + } +} + +#[test] +fn both_ready() { + let (tx1, rx1) = channel::<i32>(); + let (tx2, rx2) = channel::<i32>(); + let (tx3, rx3) = channel::<()>(); + + let _t = thread::spawn(move|| { + for _ in 0..20 { thread::yield_now(); } + tx1.send(1).unwrap(); + tx2.send(2).unwrap(); + rx3.recv().unwrap(); + }); + + select! { + a = rx1.recv() => { assert_eq!(a.unwrap(), 1); }, + a = rx2.recv() => { assert_eq!(a.unwrap(), 2); } + } + select! { + a = rx1.recv() => { assert_eq!(a.unwrap(), 1); }, + a = rx2.recv() => { assert_eq!(a.unwrap(), 2); } + } + assert_eq!(rx1.try_recv(), Err(TryRecvError::Empty)); + assert_eq!(rx2.try_recv(), Err(TryRecvError::Empty)); + tx3.send(()).unwrap(); +} + +#[test] +fn stress() { + const AMT: i32 = 10000; + let (tx1, rx1) = channel::<i32>(); + let (tx2, rx2) = channel::<i32>(); + let (tx3, rx3) = channel::<()>(); + + let _t = thread::spawn(move|| { + for i in 0..AMT { + if i % 2 == 0 { + tx1.send(i).unwrap(); + } else { + tx2.send(i).unwrap(); + } + rx3.recv().unwrap(); + } + }); + + for i in 0..AMT { + select! { + i1 = rx1.recv() => { assert!(i % 2 == 0 && i == i1.unwrap()); }, + i2 = rx2.recv() => { assert!(i % 2 == 1 && i == i2.unwrap()); } + } + tx3.send(()).unwrap(); + } +} + +#[allow(unused_must_use)] +#[test] +fn cloning() { + let (tx1, rx1) = channel::<i32>(); + let (_tx2, rx2) = channel::<i32>(); + let (tx3, rx3) = channel::<()>(); + + let _t = thread::spawn(move|| { + rx3.recv().unwrap(); + tx1.clone(); + assert_eq!(rx3.try_recv(), Err(TryRecvError::Empty)); + tx1.send(2).unwrap(); + rx3.recv().unwrap(); + }); + + tx3.send(()).unwrap(); + select! { + _i1 = rx1.recv() => {}, + _i2 = rx2.recv() => panic!() + } + tx3.send(()).unwrap(); +} + +#[allow(unused_must_use)] +#[test] +fn cloning2() { + let (tx1, rx1) = channel::<i32>(); + let (_tx2, rx2) = channel::<i32>(); + let (tx3, rx3) = channel::<()>(); + + let _t = thread::spawn(move|| { + rx3.recv().unwrap(); + tx1.clone(); + assert_eq!(rx3.try_recv(), Err(TryRecvError::Empty)); + tx1.send(2).unwrap(); + rx3.recv().unwrap(); + }); + + tx3.send(()).unwrap(); + select! { + _i1 = rx1.recv() => {}, + _i2 = rx2.recv() => panic!() + } + tx3.send(()).unwrap(); +} + +#[test] +fn cloning3() { + let (tx1, rx1) = channel::<()>(); + let (tx2, rx2) = channel::<()>(); + let (tx3, rx3) = channel::<()>(); + let _t = thread::spawn(move|| { + let s = Select::new(); + let mut h1 = s.handle(&rx1); + let mut h2 = s.handle(&rx2); + unsafe { h2.add(); } + unsafe { h1.add(); } + assert_eq!(s.wait(), h2.id()); + tx3.send(()).unwrap(); + }); + + for _ in 0..1000 { thread::yield_now(); } + drop(tx1.clone()); + tx2.send(()).unwrap(); + rx3.recv().unwrap(); +} + +#[test] +fn preflight1() { + let (tx, rx) = channel(); + tx.send(()).unwrap(); + select! { + _n = rx.recv() => {} + } +} + +#[test] +fn preflight2() { + let (tx, rx) = channel(); + tx.send(()).unwrap(); + tx.send(()).unwrap(); + select! { + _n = rx.recv() => {} + } +} + +#[test] +fn preflight3() { + let (tx, rx) = channel(); + drop(tx.clone()); + tx.send(()).unwrap(); + select! { + _n = rx.recv() => {} + } +} + +#[test] +fn preflight4() { + let (tx, rx) = channel(); + tx.send(()).unwrap(); + let s = Select::new(); + let mut h = s.handle(&rx); + unsafe { h.add(); } + assert_eq!(s.wait2(false), h.id()); +} + +#[test] +fn preflight5() { + let (tx, rx) = channel(); + tx.send(()).unwrap(); + tx.send(()).unwrap(); + let s = Select::new(); + let mut h = s.handle(&rx); + unsafe { h.add(); } + assert_eq!(s.wait2(false), h.id()); +} + +#[test] +fn preflight6() { + let (tx, rx) = channel(); + drop(tx.clone()); + tx.send(()).unwrap(); + let s = Select::new(); + let mut h = s.handle(&rx); + unsafe { h.add(); } + assert_eq!(s.wait2(false), h.id()); +} + +#[test] +fn preflight7() { + let (tx, rx) = channel::<()>(); + drop(tx); + let s = Select::new(); + let mut h = s.handle(&rx); + unsafe { h.add(); } + assert_eq!(s.wait2(false), h.id()); +} + +#[test] +fn preflight8() { + let (tx, rx) = channel(); + tx.send(()).unwrap(); + drop(tx); + rx.recv().unwrap(); + let s = Select::new(); + let mut h = s.handle(&rx); + unsafe { h.add(); } + assert_eq!(s.wait2(false), h.id()); +} + +#[test] +fn preflight9() { + let (tx, rx) = channel(); + drop(tx.clone()); + tx.send(()).unwrap(); + drop(tx); + rx.recv().unwrap(); + let s = Select::new(); + let mut h = s.handle(&rx); + unsafe { h.add(); } + assert_eq!(s.wait2(false), h.id()); +} + +#[test] +fn oneshot_data_waiting() { + let (tx1, rx1) = channel(); + let (tx2, rx2) = channel(); + let _t = thread::spawn(move|| { + select! { + _n = rx1.recv() => {} + } + tx2.send(()).unwrap(); + }); + + for _ in 0..100 { thread::yield_now() } + tx1.send(()).unwrap(); + rx2.recv().unwrap(); +} + +#[test] +fn stream_data_waiting() { + let (tx1, rx1) = channel(); + let (tx2, rx2) = channel(); + tx1.send(()).unwrap(); + tx1.send(()).unwrap(); + rx1.recv().unwrap(); + rx1.recv().unwrap(); + let _t = thread::spawn(move|| { + select! { + _n = rx1.recv() => {} + } + tx2.send(()).unwrap(); + }); + + for _ in 0..100 { thread::yield_now() } + tx1.send(()).unwrap(); + rx2.recv().unwrap(); +} + +#[test] +fn shared_data_waiting() { + let (tx1, rx1) = channel(); + let (tx2, rx2) = channel(); + drop(tx1.clone()); + tx1.send(()).unwrap(); + rx1.recv().unwrap(); + let _t = thread::spawn(move|| { + select! { + _n = rx1.recv() => {} + } + tx2.send(()).unwrap(); + }); + + for _ in 0..100 { thread::yield_now() } + tx1.send(()).unwrap(); + rx2.recv().unwrap(); +} + +#[test] +fn sync1() { + let (tx, rx) = sync_channel::<i32>(1); + tx.send(1).unwrap(); + select! { + n = rx.recv() => { assert_eq!(n.unwrap(), 1); } + } +} + +#[test] +fn sync2() { + let (tx, rx) = sync_channel::<i32>(0); + let _t = thread::spawn(move|| { + for _ in 0..100 { thread::yield_now() } + tx.send(1).unwrap(); + }); + select! { + n = rx.recv() => { assert_eq!(n.unwrap(), 1); } + } +} + +#[test] +fn sync3() { + let (tx1, rx1) = sync_channel::<i32>(0); + let (tx2, rx2): (Sender<i32>, Receiver<i32>) = channel(); + let _t = thread::spawn(move|| { tx1.send(1).unwrap(); }); + let _t = thread::spawn(move|| { tx2.send(2).unwrap(); }); + select! { + n = rx1.recv() => { + let n = n.unwrap(); + assert_eq!(n, 1); + assert_eq!(rx2.recv().unwrap(), 2); + }, + n = rx2.recv() => { + let n = n.unwrap(); + assert_eq!(n, 2); + assert_eq!(rx1.recv().unwrap(), 1); + } + } +} diff --git a/src/libstd/sync/mpsc/shared.rs b/src/libstd/sync/mpsc/shared.rs index af538b75b70..3da73ac0b82 100644 --- a/src/libstd/sync/mpsc/shared.rs +++ b/src/libstd/sync/mpsc/shared.rs @@ -1,4 +1,4 @@ -/// Shared channels +/// Shared channels. /// /// This is the flavor of channels which are not necessarily optimized for any /// particular use case, but are the most general in how they are used. Shared diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs index 59829db23cb..340dca7ce73 100644 --- a/src/libstd/sync/mutex.rs +++ b/src/libstd/sync/mutex.rs @@ -335,7 +335,7 @@ impl<T: ?Sized> Mutex<T> { /// Returns a mutable reference to the underlying data. /// /// Since this call borrows the `Mutex` mutably, no actual locking needs to - /// take place---the mutable borrow statically guarantees no locks exist. + /// take place -- the mutable borrow statically guarantees no locks exist. /// /// # Errors /// diff --git a/src/libstd/sync/once.rs b/src/libstd/sync/once.rs index fcab2ffe144..656389789d7 100644 --- a/src/libstd/sync/once.rs +++ b/src/libstd/sync/once.rs @@ -228,7 +228,7 @@ impl Once { /// result in an immediate panic. If `f` panics, the `Once` will remain /// in a poison state. If `f` does _not_ panic, the `Once` will no /// longer be in a poison state and all future calls to `call_once` or - /// `call_one_force` will no-op. + /// `call_one_force` will be no-ops. /// /// The closure `f` is yielded a [`OnceState`] structure which can be used /// to query the poison status of the `Once`. @@ -279,7 +279,7 @@ impl Once { }); } - /// Returns true if some `call_once` call has completed + /// Returns `true` if some `call_once` call has completed /// successfully. Specifically, `is_completed` will return false in /// the following situations: /// * `call_once` was not called at all, @@ -465,7 +465,7 @@ impl<'a> Drop for Finish<'a> { } impl OnceState { - /// Returns whether the associated [`Once`] was poisoned prior to the + /// Returns `true` if the associated [`Once`] was poisoned prior to the /// invocation of the closure passed to [`call_once_force`]. /// /// [`call_once_force`]: struct.Once.html#method.call_once_force diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs index 7fbe0b8c199..730362e2ac8 100644 --- a/src/libstd/sync/rwlock.rs +++ b/src/libstd/sync/rwlock.rs @@ -314,7 +314,7 @@ impl<T: ?Sized> RwLock<T> { /// Determines whether the lock is poisoned. /// /// If another thread is active, the lock can still become poisoned at any - /// time. You should not trust a `false` value for program correctness + /// time. You should not trust a `false` value for program correctness /// without additional synchronization. /// /// # Examples @@ -384,7 +384,7 @@ impl<T: ?Sized> RwLock<T> { /// Returns a mutable reference to the underlying data. /// /// Since this call borrows the `RwLock` mutably, no actual locking needs to - /// take place---the mutable borrow statically guarantees no locks exist. + /// take place -- the mutable borrow statically guarantees no locks exist. /// /// # Errors /// diff --git a/src/libstd/sys/cloudabi/abi/cloudabi.rs b/src/libstd/sys/cloudabi/abi/cloudabi.rs index 0bf8c2d5998..83d45b3547b 100644 --- a/src/libstd/sys/cloudabi/abi/cloudabi.rs +++ b/src/libstd/sys/cloudabi/abi/cloudabi.rs @@ -673,11 +673,11 @@ bitflags! { /// Methods of synchronizing memory with physical storage. #[repr(C)] pub struct msflags: u8 { - /// Perform asynchronous writes. + /// Performs asynchronous writes. const ASYNC = 0x01; - /// Invalidate cached data. + /// Invalidates cached data. const INVALIDATE = 0x02; - /// Perform synchronous writes. + /// Performs synchronous writes. const SYNC = 0x04; } } @@ -1750,11 +1750,9 @@ fn tcb_layout_test_64() { /// Entry point for additionally created threads. /// -/// **tid**: -/// Thread ID of the current thread. +/// `tid`: thread ID of the current thread. /// -/// **aux**: -/// Copy of the value stored in +/// `aux`: copy of the value stored in /// [`threadattr.argument`](struct.threadattr.html#structfield.argument). pub type threadentry = unsafe extern "C" fn( tid: tid, @@ -2590,7 +2588,7 @@ pub unsafe fn mem_map(addr_: *mut (), len_: usize, prot_: mprot, flags_: mflags, cloudabi_sys_mem_map(addr_, len_, prot_, flags_, fd_, off_, mem_) } -/// Change the protection of a memory mapping. +/// Changes the protection of a memory mapping. /// /// ## Parameters /// @@ -2604,7 +2602,7 @@ pub unsafe fn mem_protect(mapping_: &mut [u8], prot_: mprot) -> errno { cloudabi_sys_mem_protect(mapping_.as_mut_ptr() as *mut (), mapping_.len(), prot_) } -/// Synchronize a region of memory with its physical storage. +/// Synchronizes a region of memory with its physical storage. /// /// ## Parameters /// diff --git a/src/libstd/sys/mod.rs b/src/libstd/sys/mod.rs index 99ef74179c2..0a56f4fad6d 100644 --- a/src/libstd/sys/mod.rs +++ b/src/libstd/sys/mod.rs @@ -1,4 +1,4 @@ -//! Platform-dependent platform abstraction +//! Platform-dependent platform abstraction. //! //! The `std::sys` module is the abstracted interface through which //! `std` talks to the underlying operating system. It has different diff --git a/src/libstd/sys/redox/ext/fs.rs b/src/libstd/sys/redox/ext/fs.rs index 04edfd6851d..8b81273f201 100644 --- a/src/libstd/sys/redox/ext/fs.rs +++ b/src/libstd/sys/redox/ext/fs.rs @@ -117,7 +117,7 @@ pub trait OpenOptionsExt { #[stable(feature = "fs_ext", since = "1.1.0")] fn mode(&mut self, mode: u32) -> &mut Self; - /// Pass custom flags to the `flags` argument of `open`. + /// Passes custom flags to the `flags` argument of `open`. /// /// The bits that define the access mode are masked out with `O_ACCMODE`, to /// ensure they do not interfere with the access mode set by Rusts options. @@ -287,9 +287,9 @@ impl FileTypeExt for fs::FileType { /// # Note /// /// On Windows, you must specify whether a symbolic link points to a file -/// or directory. Use `os::windows::fs::symlink_file` to create a +/// or directory. Use `os::windows::fs::symlink_file` to create a /// symbolic link to a file, or `os::windows::fs::symlink_dir` to create a -/// symbolic link to a directory. Additionally, the process must have +/// symbolic link to a directory. Additionally, the process must have /// `SeCreateSymbolicLinkPrivilege` in order to be able to create a /// symbolic link. /// diff --git a/src/libstd/sys/redox/ext/net.rs b/src/libstd/sys/redox/ext/net.rs index 76c68829b7f..7411b8e068f 100644 --- a/src/libstd/sys/redox/ext/net.rs +++ b/src/libstd/sys/redox/ext/net.rs @@ -60,7 +60,7 @@ impl SocketAddr { None } - /// Returns true if and only if the address is unnamed. + /// Returns `true` if the address is unnamed. /// /// # Examples /// @@ -374,7 +374,7 @@ impl UnixStream { /// ``` /// /// # Platform specific - /// On Redox this always returns None. + /// On Redox this always returns `None`. #[stable(feature = "unix_socket_redox", since = "1.29")] pub fn take_error(&self) -> io::Result<Option<io::Error>> { Ok(None) @@ -635,7 +635,7 @@ impl UnixListener { /// ``` /// /// # Platform specific - /// On Redox this always returns None. + /// On Redox this always returns `None`. #[stable(feature = "unix_socket_redox", since = "1.29")] pub fn take_error(&self) -> io::Result<Option<io::Error>> { Ok(None) diff --git a/src/libstd/sys/redox/ext/process.rs b/src/libstd/sys/redox/ext/process.rs index 941fba8755b..1dcc1169510 100644 --- a/src/libstd/sys/redox/ext/process.rs +++ b/src/libstd/sys/redox/ext/process.rs @@ -13,13 +13,13 @@ use sys_common::{AsInnerMut, AsInner, FromInner, IntoInner}; /// [`process::Command`]: ../../../../std/process/struct.Command.html #[stable(feature = "rust1", since = "1.0.0")] pub trait CommandExt { - /// Sets the child process's user id. This translates to a + /// Sets the child process's user ID. This translates to a /// `setuid` call in the child process. Failure in the `setuid` /// call will cause the spawn to fail. #[stable(feature = "rust1", since = "1.0.0")] fn uid(&mut self, id: u32) -> &mut process::Command; - /// Similar to `uid`, but sets the group id of the child process. This has + /// Similar to `uid`, but sets the group ID of the child process. This has /// the same semantics as the `uid` field. #[stable(feature = "rust1", since = "1.0.0")] fn gid(&mut self, id: u32) -> &mut process::Command; diff --git a/src/libstd/sys/redox/mutex.rs b/src/libstd/sys/redox/mutex.rs index 42424da858f..bf39cc48591 100644 --- a/src/libstd/sys/redox/mutex.rs +++ b/src/libstd/sys/redox/mutex.rs @@ -50,7 +50,7 @@ pub struct Mutex { } impl Mutex { - /// Create a new mutex. + /// Creates a new mutex. pub const fn new() -> Self { Mutex { lock: UnsafeCell::new(0), diff --git a/src/libstd/sys/redox/process.rs b/src/libstd/sys/redox/process.rs index 4199ab98cf1..9e23c537f22 100644 --- a/src/libstd/sys/redox/process.rs +++ b/src/libstd/sys/redox/process.rs @@ -561,7 +561,7 @@ impl ExitCode { } } -/// The unique id of the process (this should never be negative). +/// The unique ID of the process (this should never be negative). pub struct Process { pid: usize, status: Option<ExitStatus>, diff --git a/src/libstd/sys/redox/syscall/call.rs b/src/libstd/sys/redox/syscall/call.rs index b9e2b476cec..b9abb48a8d3 100644 --- a/src/libstd/sys/redox/syscall/call.rs +++ b/src/libstd/sys/redox/syscall/call.rs @@ -25,7 +25,7 @@ pub unsafe fn brk(addr: usize) -> Result<usize> { syscall1(SYS_BRK, addr) } -/// Change the process's working directory +/// Changes the process's working directory. /// /// This function will attempt to set the process's working directory to `path`, which can be /// either a relative, scheme relative, or absolute path. @@ -47,90 +47,90 @@ pub fn chmod<T: AsRef<[u8]>>(path: T, mode: usize) -> Result<usize> { unsafe { syscall3(SYS_CHMOD, path.as_ref().as_ptr() as usize, path.as_ref().len(), mode) } } -/// Produce a fork of the current process, or a new process thread +/// Produces a fork of the current process, or a new process thread. pub unsafe fn clone(flags: usize) -> Result<usize> { syscall1_clobber(SYS_CLONE, flags) } -/// Close a file +/// Closes a file. pub fn close(fd: usize) -> Result<usize> { unsafe { syscall1(SYS_CLOSE, fd) } } -/// Get the current system time +/// Gets the current system time. pub fn clock_gettime(clock: usize, tp: &mut TimeSpec) -> Result<usize> { unsafe { syscall2(SYS_CLOCK_GETTIME, clock, tp as *mut TimeSpec as usize) } } -/// Copy and transform a file descriptor +/// Copies and transforms a file descriptor. pub fn dup(fd: usize, buf: &[u8]) -> Result<usize> { unsafe { syscall3(SYS_DUP, fd, buf.as_ptr() as usize, buf.len()) } } -/// Copy and transform a file descriptor +/// Copies and transforms a file descriptor. pub fn dup2(fd: usize, newfd: usize, buf: &[u8]) -> Result<usize> { unsafe { syscall4(SYS_DUP2, fd, newfd, buf.as_ptr() as usize, buf.len()) } } -/// Exit the current process +/// Exits the current process. pub fn exit(status: usize) -> Result<usize> { unsafe { syscall1(SYS_EXIT, status) } } -/// Change file permissions +/// Changes file permissions. pub fn fchmod(fd: usize, mode: u16) -> Result<usize> { unsafe { syscall2(SYS_FCHMOD, fd, mode as usize) } } -/// Change file ownership +/// Changes file ownership. pub fn fchown(fd: usize, uid: u32, gid: u32) -> Result<usize> { unsafe { syscall3(SYS_FCHOWN, fd, uid as usize, gid as usize) } } -/// Change file descriptor flags +/// Changes file descriptor flags. pub fn fcntl(fd: usize, cmd: usize, arg: usize) -> Result<usize> { unsafe { syscall3(SYS_FCNTL, fd, cmd, arg) } } -/// Replace the current process with a new executable +/// Replaces the current process with a new executable. pub fn fexec(fd: usize, args: &[[usize; 2]], vars: &[[usize; 2]]) -> Result<usize> { unsafe { syscall5(SYS_FEXEC, fd, args.as_ptr() as usize, args.len(), vars.as_ptr() as usize, vars.len()) } } -/// Map a file into memory +/// Maps a file into memory. pub unsafe fn fmap(fd: usize, offset: usize, size: usize) -> Result<usize> { syscall3(SYS_FMAP, fd, offset, size) } -/// Unmap a memory-mapped file +/// Unmaps a memory-mapped file. pub unsafe fn funmap(addr: usize) -> Result<usize> { syscall1(SYS_FUNMAP, addr) } -/// Retrieve the canonical path of a file +/// Retrieves the canonical path of a file. pub fn fpath(fd: usize, buf: &mut [u8]) -> Result<usize> { unsafe { syscall3(SYS_FPATH, fd, buf.as_mut_ptr() as usize, buf.len()) } } -/// Rename a file +/// Renames a file. pub fn frename<T: AsRef<[u8]>>(fd: usize, path: T) -> Result<usize> { unsafe { syscall3(SYS_FRENAME, fd, path.as_ref().as_ptr() as usize, path.as_ref().len()) } } -/// Get metadata about a file +/// Gets metadata about a file. pub fn fstat(fd: usize, stat: &mut Stat) -> Result<usize> { unsafe { syscall3(SYS_FSTAT, fd, stat as *mut Stat as usize, mem::size_of::<Stat>()) } } -/// Get metadata about a filesystem +/// Gets metadata about a filesystem. pub fn fstatvfs(fd: usize, stat: &mut StatVfs) -> Result<usize> { unsafe { syscall3(SYS_FSTATVFS, fd, stat as *mut StatVfs as usize, mem::size_of::<StatVfs>()) } } -/// Sync a file descriptor to its underlying medium +/// Syncs a file descriptor to its underlying medium. pub fn fsync(fd: usize) -> Result<usize> { unsafe { syscall1(SYS_FSYNC, fd) } } @@ -152,113 +152,113 @@ pub unsafe fn futex(addr: *mut i32, op: usize, val: i32, val2: usize, addr2: *mu syscall5(SYS_FUTEX, addr as usize, op, (val as isize) as usize, val2, addr2 as usize) } -/// Get the current working directory +/// Gets the current working directory. pub fn getcwd(buf: &mut [u8]) -> Result<usize> { unsafe { syscall2(SYS_GETCWD, buf.as_mut_ptr() as usize, buf.len()) } } -/// Get the effective group ID +/// Gets the effective group ID. pub fn getegid() -> Result<usize> { unsafe { syscall0(SYS_GETEGID) } } -/// Get the effective namespace +/// Gets the effective namespace. pub fn getens() -> Result<usize> { unsafe { syscall0(SYS_GETENS) } } -/// Get the effective user ID +/// Gets the effective user ID. pub fn geteuid() -> Result<usize> { unsafe { syscall0(SYS_GETEUID) } } -/// Get the current group ID +/// Gets the current group ID. pub fn getgid() -> Result<usize> { unsafe { syscall0(SYS_GETGID) } } -/// Get the current namespace +/// Gets the current namespace. pub fn getns() -> Result<usize> { unsafe { syscall0(SYS_GETNS) } } -/// Get the current process ID +/// Gets the current process ID. pub fn getpid() -> Result<usize> { unsafe { syscall0(SYS_GETPID) } } -/// Get the process group ID +/// Gets the process group ID. pub fn getpgid(pid: usize) -> Result<usize> { unsafe { syscall1(SYS_GETPGID, pid) } } -/// Get the parent process ID +/// Gets the parent process ID. pub fn getppid() -> Result<usize> { unsafe { syscall0(SYS_GETPPID) } } -/// Get the current user ID +/// Gets the current user ID. pub fn getuid() -> Result<usize> { unsafe { syscall0(SYS_GETUID) } } -/// Set the I/O privilege level +/// Sets the I/O privilege level pub unsafe fn iopl(level: usize) -> Result<usize> { syscall1(SYS_IOPL, level) } -/// Send a signal `sig` to the process identified by `pid` +/// Sends a signal `sig` to the process identified by `pid`. pub fn kill(pid: usize, sig: usize) -> Result<usize> { unsafe { syscall2(SYS_KILL, pid, sig) } } -/// Create a link to a file +/// Creates a link to a file. pub unsafe fn link(old: *const u8, new: *const u8) -> Result<usize> { syscall2(SYS_LINK, old as usize, new as usize) } -/// Seek to `offset` bytes in a file descriptor +/// Seeks to `offset` bytes in a file descriptor. pub fn lseek(fd: usize, offset: isize, whence: usize) -> Result<usize> { unsafe { syscall3(SYS_LSEEK, fd, offset as usize, whence) } } -/// Make a new scheme namespace +/// Makes a new scheme namespace. pub fn mkns(schemes: &[[usize; 2]]) -> Result<usize> { unsafe { syscall2(SYS_MKNS, schemes.as_ptr() as usize, schemes.len()) } } -/// Sleep for the time specified in `req` +/// Sleeps for the time specified in `req`. pub fn nanosleep(req: &TimeSpec, rem: &mut TimeSpec) -> Result<usize> { unsafe { syscall2(SYS_NANOSLEEP, req as *const TimeSpec as usize, rem as *mut TimeSpec as usize) } } -/// Open a file +/// Opens a file. pub fn open<T: AsRef<[u8]>>(path: T, flags: usize) -> Result<usize> { unsafe { syscall3(SYS_OPEN, path.as_ref().as_ptr() as usize, path.as_ref().len(), flags) } } -/// Allocate pages, linearly in physical memory +/// Allocates pages, linearly in physical memory. pub unsafe fn physalloc(size: usize) -> Result<usize> { syscall1(SYS_PHYSALLOC, size) } -/// Free physically allocated pages +/// Frees physically allocated pages. pub unsafe fn physfree(physical_address: usize, size: usize) -> Result<usize> { syscall2(SYS_PHYSFREE, physical_address, size) } -/// Map physical memory to virtual memory +/// Maps physical memory to virtual memory. pub unsafe fn physmap(physical_address: usize, size: usize, flags: usize) -> Result<usize> { syscall3(SYS_PHYSMAP, physical_address, size, flags) } -/// Unmap previously mapped physical memory +/// Unmaps previously mapped physical memory. pub unsafe fn physunmap(virtual_address: usize) -> Result<usize> { syscall1(SYS_PHYSUNMAP, virtual_address) } -/// Create a pair of file descriptors referencing the read and write ends of a pipe +/// Creates a pair of file descriptors referencing the read and write ends of a pipe. pub fn pipe2(fds: &mut [usize; 2], flags: usize) -> Result<usize> { unsafe { syscall2(SYS_PIPE2, fds.as_ptr() as usize, flags) } } @@ -268,32 +268,32 @@ pub fn read(fd: usize, buf: &mut [u8]) -> Result<usize> { unsafe { syscall3(SYS_READ, fd, buf.as_mut_ptr() as usize, buf.len()) } } -/// Remove a directory +/// Removes a directory. pub fn rmdir<T: AsRef<[u8]>>(path: T) -> Result<usize> { unsafe { syscall2(SYS_RMDIR, path.as_ref().as_ptr() as usize, path.as_ref().len()) } } -/// Set the process group ID +/// Sets the process group ID. pub fn setpgid(pid: usize, pgid: usize) -> Result<usize> { unsafe { syscall2(SYS_SETPGID, pid, pgid) } } -/// Set the current process group IDs +/// Sets the current process group IDs. pub fn setregid(rgid: usize, egid: usize) -> Result<usize> { unsafe { syscall2(SYS_SETREGID, rgid, egid) } } -/// Make a new scheme namespace +/// Makes a new scheme namespace. pub fn setrens(rns: usize, ens: usize) -> Result<usize> { unsafe { syscall2(SYS_SETRENS, rns, ens) } } -/// Set the current process user IDs +/// Sets the current process user IDs. pub fn setreuid(ruid: usize, euid: usize) -> Result<usize> { unsafe { syscall2(SYS_SETREUID, ruid, euid) } } -/// Set up a signal handler +/// Sets up a signal handler. pub fn sigaction(sig: usize, act: Option<&SigAction>, oldact: Option<&mut SigAction>) -> Result<usize> { unsafe { syscall4(SYS_SIGACTION, sig, @@ -302,27 +302,27 @@ pub fn sigaction(sig: usize, act: Option<&SigAction>, oldact: Option<&mut SigAct restorer as usize) } } -// Return from signal handler +/// Returns from signal handler. pub fn sigreturn() -> Result<usize> { unsafe { syscall0(SYS_SIGRETURN) } } -/// Remove a file +/// Removes a file. pub fn unlink<T: AsRef<[u8]>>(path: T) -> Result<usize> { unsafe { syscall2(SYS_UNLINK, path.as_ref().as_ptr() as usize, path.as_ref().len()) } } -/// Convert a virtual address to a physical one +/// Converts a virtual address to a physical one. pub unsafe fn virttophys(virtual_address: usize) -> Result<usize> { syscall1(SYS_VIRTTOPHYS, virtual_address) } -/// Check if a child process has exited or received a signal +/// Checks if a child process has exited or received a signal. pub fn waitpid(pid: usize, status: &mut usize, options: usize) -> Result<usize> { unsafe { syscall3(SYS_WAITPID, pid, status as *mut usize as usize, options) } } -/// Write a buffer to a file descriptor +/// Writes a buffer to a file descriptor. /// /// The kernel will attempt to write the bytes in `buf` to the file descriptor `fd`, returning /// either an `Err`, explained below, or `Ok(count)` where `count` is the number of bytes which @@ -340,7 +340,7 @@ pub fn write(fd: usize, buf: &[u8]) -> Result<usize> { unsafe { syscall3(SYS_WRITE, fd, buf.as_ptr() as usize, buf.len()) } } -/// Yield the process's time slice to the kernel +/// Yields the process's time slice to the kernel. /// /// This function will return Ok(0) on success pub fn sched_yield() -> Result<usize> { diff --git a/src/libstd/sys/redox/syscall/flag.rs b/src/libstd/sys/redox/syscall/flag.rs index a41bc6d4a8b..5820f1ad03a 100644 --- a/src/libstd/sys/redox/syscall/flag.rs +++ b/src/libstd/sys/redox/syscall/flag.rs @@ -107,42 +107,42 @@ pub const WNOHANG: usize = 0x01; pub const WUNTRACED: usize = 0x02; pub const WCONTINUED: usize = 0x08; -/// True if status indicates the child is stopped. +/// Returns `true` if status indicates the child is stopped. pub fn wifstopped(status: usize) -> bool { (status & 0xff) == 0x7f } -/// If wifstopped(status), the signal that stopped the child. +/// If wifstopped(status), returns the signal that stopped the child. pub fn wstopsig(status: usize) -> usize { (status >> 8) & 0xff } -/// True if status indicates the child continued after a stop. +/// Returns `true` if status indicates the child continued after a stop. pub fn wifcontinued(status: usize) -> bool { status == 0xffff } -/// True if STATUS indicates termination by a signal. +/// Returns `true` if status indicates termination by a signal. pub fn wifsignaled(status: usize) -> bool { ((status & 0x7f) + 1) as i8 >= 2 } -/// If wifsignaled(status), the terminating signal. +/// If wifsignaled(status), returns the terminating signal. pub fn wtermsig(status: usize) -> usize { status & 0x7f } -/// True if status indicates normal termination. +/// Returns `true` if status indicates normal termination. pub fn wifexited(status: usize) -> bool { wtermsig(status) == 0 } -/// If wifexited(status), the exit status. +/// If wifexited(status), returns the exit status. pub fn wexitstatus(status: usize) -> usize { (status >> 8) & 0xff } -/// True if status indicates a core dump was created. +/// Returns `true` if status indicates a core dump was created. pub fn wcoredump(status: usize) -> bool { (status & 0x80) != 0 } diff --git a/src/libstd/sys/sgx/abi/thread.rs b/src/libstd/sys/sgx/abi/thread.rs index 588fbcd9d43..86fe09d0035 100644 --- a/src/libstd/sys/sgx/abi/thread.rs +++ b/src/libstd/sys/sgx/abi/thread.rs @@ -1,6 +1,6 @@ use fortanix_sgx_abi::Tcs; -/// Get the ID for the current thread. The ID is guaranteed to be unique among +/// Gets the ID for the current thread. The ID is guaranteed to be unique among /// all currently running threads in the enclave, and it is guaranteed to be /// constant for the lifetime of the thread. More specifically for SGX, there /// is a one-to-one correspondence of the ID to the address of the TCS. diff --git a/src/libstd/sys/sgx/abi/tls.rs b/src/libstd/sys/sgx/abi/tls.rs index b8e09d58deb..e1fc3696845 100644 --- a/src/libstd/sys/sgx/abi/tls.rs +++ b/src/libstd/sys/sgx/abi/tls.rs @@ -182,7 +182,7 @@ mod sync_bitset { self.0[hi].fetch_and(!lo, Ordering::Relaxed); } - /// Set any unset bit. Not atomic. Returns `None` if all bits were + /// Sets any unset bit. Not atomic. Returns `None` if all bits were /// observed to be set. pub fn set(&self) -> Option<usize> { 'elems: for (idx, elem) in self.0.iter().enumerate() { diff --git a/src/libstd/sys/sgx/abi/usercalls/alloc.rs b/src/libstd/sys/sgx/abi/usercalls/alloc.rs index 8d0013a235a..0ccbbbc6501 100644 --- a/src/libstd/sys/sgx/abi/usercalls/alloc.rs +++ b/src/libstd/sys/sgx/abi/usercalls/alloc.rs @@ -63,44 +63,49 @@ pub unsafe trait UserSafe { /// Construct a pointer to `Self` given a memory range in user space. /// - /// NB. This takes a size, not a length! + /// N.B., this takes a size, not a length! /// /// # Safety + /// /// The caller must ensure the memory range is in user memory, is the /// correct size and is correctly aligned and points to the right type. unsafe fn from_raw_sized_unchecked(ptr: *mut u8, size: usize) -> *mut Self; /// Construct a pointer to `Self` given a memory range. /// - /// NB. This takes a size, not a length! + /// N.B., this takes a size, not a length! /// /// # Safety + /// /// The caller must ensure the memory range points to the correct type. /// /// # Panics + /// /// This function panics if: /// - /// * The pointer is not aligned - /// * The pointer is null - /// * The pointed-to range is not in user memory + /// * the pointer is not aligned. + /// * the pointer is null. + /// * the pointed-to range is not in user memory. unsafe fn from_raw_sized(ptr: *mut u8, size: usize) -> NonNull<Self> { let ret = Self::from_raw_sized_unchecked(ptr, size); Self::check_ptr(ret); NonNull::new_unchecked(ret as _) } - /// Check if a pointer may point to Self in user memory. + /// Checks if a pointer may point to `Self` in user memory. /// /// # Safety + /// /// The caller must ensure the memory range points to the correct type and /// length (if this is a slice). /// /// # Panics + /// /// This function panics if: /// - /// * The pointer is not aligned - /// * The pointer is null - /// * The pointed-to range is not in user memory + /// * the pointer is not aligned. + /// * the pointer is null. + /// * the pointed-to range is not in user memory. unsafe fn check_ptr(ptr: *const Self) { let is_aligned = |p| -> bool { 0 == (p as usize) & (Self::align_of() - 1) @@ -188,7 +193,7 @@ impl<T: ?Sized> User<T> where T: UserSafe { } } - /// Copy `val` into freshly allocated space in user memory. + /// Copies `val` into freshly allocated space in user memory. pub fn new_from_enclave(val: &T) -> Self { unsafe { let ret = Self::new_uninit_bytes(mem::size_of_val(val)); @@ -201,7 +206,7 @@ impl<T: ?Sized> User<T> where T: UserSafe { } } - /// Create an owned `User<T>` from a raw pointer. + /// Creates an owned `User<T>` from a raw pointer. /// /// # Safety /// The caller must ensure `ptr` points to `T`, is freeable with the `free` @@ -218,7 +223,7 @@ impl<T: ?Sized> User<T> where T: UserSafe { User(NonNull::new_userref(ptr)) } - /// Convert this value into a raw pointer. The value will no longer be + /// Converts this value into a raw pointer. The value will no longer be /// automatically freed. pub fn into_raw(self) -> *mut T { let ret = self.0; @@ -242,7 +247,7 @@ impl<T> User<[T]> where [T]: UserSafe { Self::new_uninit_bytes(n * mem::size_of::<T>()) } - /// Create an owned `User<[T]>` from a raw thin pointer and a slice length. + /// Creates an owned `User<[T]>` from a raw thin pointer and a slice length. /// /// # Safety /// The caller must ensure `ptr` points to `len` elements of `T`, is @@ -262,7 +267,7 @@ impl<T> User<[T]> where [T]: UserSafe { #[unstable(feature = "sgx_platform", issue = "56975")] impl<T: ?Sized> UserRef<T> where T: UserSafe { - /// Create a `&UserRef<[T]>` from a raw pointer. + /// Creates a `&UserRef<[T]>` from a raw pointer. /// /// # Safety /// The caller must ensure `ptr` points to `T`. @@ -278,7 +283,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe { &*(ptr as *const Self) } - /// Create a `&mut UserRef<[T]>` from a raw pointer. See the struct + /// Creates a `&mut UserRef<[T]>` from a raw pointer. See the struct /// documentation for the nuances regarding a `&mut UserRef<T>`. /// /// # Safety @@ -295,7 +300,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe { &mut*(ptr as *mut Self) } - /// Copy `val` into user memory. + /// Copies `val` into user memory. /// /// # Panics /// This function panics if the destination doesn't have the same size as @@ -311,7 +316,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe { } } - /// Copy the value from user memory and place it into `dest`. + /// Copies the value from user memory and place it into `dest`. /// /// # Panics /// This function panics if the destination doesn't have the same size as @@ -340,7 +345,7 @@ impl<T: ?Sized> UserRef<T> where T: UserSafe { #[unstable(feature = "sgx_platform", issue = "56975")] impl<T> UserRef<T> where T: UserSafe { - /// Copy the value from user memory into enclave memory. + /// Copies the value from user memory into enclave memory. pub fn to_enclave(&self) -> T { unsafe { ptr::read(self.0.get()) } } @@ -348,7 +353,7 @@ impl<T> UserRef<T> where T: UserSafe { #[unstable(feature = "sgx_platform", issue = "56975")] impl<T> UserRef<[T]> where [T]: UserSafe { - /// Create a `&UserRef<[T]>` from a raw thin pointer and a slice length. + /// Creates a `&UserRef<[T]>` from a raw thin pointer and a slice length. /// /// # Safety /// The caller must ensure `ptr` points to `n` elements of `T`. @@ -363,7 +368,7 @@ impl<T> UserRef<[T]> where [T]: UserSafe { &*(<[T]>::from_raw_sized(ptr as _, len * mem::size_of::<T>()).as_ptr() as *const Self) } - /// Create a `&mut UserRef<[T]>` from a raw thin pointer and a slice length. + /// Creates a `&mut UserRef<[T]>` from a raw thin pointer and a slice length. /// See the struct documentation for the nuances regarding a /// `&mut UserRef<T>`. /// @@ -395,7 +400,7 @@ impl<T> UserRef<[T]> where [T]: UserSafe { unsafe { (*self.0.get()).len() } } - /// Copy the value from user memory and place it into `dest`. Afterwards, + /// Copies the value from user memory and place it into `dest`. Afterwards, /// `dest` will contain exactly `self.len()` elements. /// /// # Panics @@ -411,7 +416,7 @@ impl<T> UserRef<[T]> where [T]: UserSafe { } } - /// Copy the value from user memory into a vector in enclave memory. + /// Copies the value from user memory into a vector in enclave memory. pub fn to_enclave(&self) -> Vec<T> { let mut ret = Vec::with_capacity(self.len()); self.copy_to_enclave_vec(&mut ret); @@ -526,7 +531,7 @@ impl<T, I: SliceIndex<[T]>> IndexMut<I> for UserRef<[T]> where [T]: UserSafe, I: #[unstable(feature = "sgx_platform", issue = "56975")] impl UserRef<super::raw::ByteBuffer> { - /// Copy the user memory range pointed to by the user `ByteBuffer` to + /// Copies the user memory range pointed to by the user `ByteBuffer` to /// enclave memory. /// /// # Panics @@ -537,7 +542,12 @@ impl UserRef<super::raw::ByteBuffer> { pub fn copy_user_buffer(&self) -> Vec<u8> { unsafe { let buf = self.to_enclave(); - User::from_raw_parts(buf.data as _, buf.len).to_enclave() + if buf.len > 0 { + User::from_raw_parts(buf.data as _, buf.len).to_enclave() + } else { + // Mustn't look at `data` or call `free` if `len` is `0`. + Vec::with_capacity(0) + } } } } diff --git a/src/libstd/sys/sgx/abi/usercalls/mod.rs b/src/libstd/sys/sgx/abi/usercalls/mod.rs index 4e889c172ef..bae044b906b 100644 --- a/src/libstd/sys/sgx/abi/usercalls/mod.rs +++ b/src/libstd/sys/sgx/abi/usercalls/mod.rs @@ -22,7 +22,8 @@ pub fn read(fd: Fd, buf: &mut [u8]) -> IoResult<usize> { #[unstable(feature = "sgx_platform", issue = "56975")] pub fn read_alloc(fd: Fd) -> IoResult<Vec<u8>> { unsafe { - let mut userbuf = alloc::User::<ByteBuffer>::uninitialized(); + let userbuf = ByteBuffer { data: ::ptr::null_mut(), len: 0 }; + let mut userbuf = alloc::User::new_from_enclave(&userbuf); raw::read_alloc(fd, userbuf.as_raw_mut_ptr()).from_sgx_result()?; Ok(userbuf.copy_user_buffer()) } diff --git a/src/libstd/sys/sgx/abi/usercalls/raw.rs b/src/libstd/sys/sgx/abi/usercalls/raw.rs index 27f780ca224..004cf57602b 100644 --- a/src/libstd/sys/sgx/abi/usercalls/raw.rs +++ b/src/libstd/sys/sgx/abi/usercalls/raw.rs @@ -12,14 +12,16 @@ extern "C" { fn usercall(nr: u64, p1: u64, p2: u64, _ignore: u64, p3: u64, p4: u64) -> UsercallReturn; } -/// Perform the raw usercall operation as defined in the ABI calling convention. +/// Performs the raw usercall operation as defined in the ABI calling convention. /// /// # Safety +/// /// The caller must ensure to pass parameters appropriate for the usercall `nr` /// and to observe all requirements specified in the ABI. /// /// # Panics -/// Panics if `nr` is 0. +/// +/// Panics if `nr` is `0`. #[unstable(feature = "sgx_platform", issue = "56975")] pub unsafe fn do_usercall(nr: u64, p1: u64, p2: u64, p3: u64, p4: u64) -> (u64, u64) { if nr==0 { panic!("Invalid usercall number {}",nr) } diff --git a/src/libstd/sys/sgx/ext/arch.rs b/src/libstd/sys/sgx/ext/arch.rs index 3bd87b5d265..97f7d9181a5 100644 --- a/src/libstd/sys/sgx/ext/arch.rs +++ b/src/libstd/sys/sgx/ext/arch.rs @@ -41,7 +41,7 @@ pub fn egetkey(request: &Align512<[u8; 512]>) -> Result<Align16<[u8; 16]>, u32> ); match error { - 0 => Ok(out.into_inner()), + 0 => Ok(out.into_initialized()), err => Err(err), } } @@ -69,6 +69,6 @@ pub fn ereport( "{rdx}"(report.as_mut_ptr()) ); - report.into_inner() + report.into_initialized() } } diff --git a/src/libstd/sys/sgx/rwlock.rs b/src/libstd/sys/sgx/rwlock.rs index 43ceae7d33b..33163a556c1 100644 --- a/src/libstd/sys/sgx/rwlock.rs +++ b/src/libstd/sys/sgx/rwlock.rs @@ -19,9 +19,6 @@ unsafe fn rw_lock_size_assert(r: RWLock) { mem::transmute::<RWLock, [u8; 128]>(r); } -//unsafe impl Send for RWLock {} -//unsafe impl Sync for RWLock {} // FIXME - impl RWLock { pub const fn new() -> RWLock { RWLock { diff --git a/src/libstd/sys/sgx/waitqueue.rs b/src/libstd/sys/sgx/waitqueue.rs index 51c00a1433e..aec643b3175 100644 --- a/src/libstd/sys/sgx/waitqueue.rs +++ b/src/libstd/sys/sgx/waitqueue.rs @@ -3,7 +3,7 @@ /// This queue is used to implement condition variable and mutexes. /// /// Users of this API are expected to use the `WaitVariable<T>` type. Since -/// that type is not `Sync`, it needs to be protected by e.g. a `SpinMutex` to +/// that type is not `Sync`, it needs to be protected by e.g., a `SpinMutex` to /// allow shared access. /// /// Since userspace may send spurious wake-ups, the wakeup event state is @@ -136,7 +136,7 @@ impl WaitQueue { self.inner.is_empty() } - /// Add the calling thread to the WaitVariable's wait queue, then wait + /// Adds the calling thread to the `WaitVariable`'s wait queue, then wait /// until a wakeup event. /// /// This function does not return until this thread has been awoken. diff --git a/src/libstd/sys/unix/ext/fs.rs b/src/libstd/sys/unix/ext/fs.rs index e962d09e274..abcce3ab829 100644 --- a/src/libstd/sys/unix/ext/fs.rs +++ b/src/libstd/sys/unix/ext/fs.rs @@ -684,7 +684,7 @@ impl MetadataExt for fs::Metadata { /// [`FileType`]: ../../../../std/fs/struct.FileType.html #[stable(feature = "file_type_ext", since = "1.5.0")] pub trait FileTypeExt { - /// Returns whether this file type is a block device. + /// Returns `true` if this file type is a block device. /// /// # Examples /// @@ -702,7 +702,7 @@ pub trait FileTypeExt { /// ``` #[stable(feature = "file_type_ext", since = "1.5.0")] fn is_block_device(&self) -> bool; - /// Returns whether this file type is a char device. + /// Returns `true` if this file type is a char device. /// /// # Examples /// @@ -720,7 +720,7 @@ pub trait FileTypeExt { /// ``` #[stable(feature = "file_type_ext", since = "1.5.0")] fn is_char_device(&self) -> bool; - /// Returns whether this file type is a fifo. + /// Returns `true` if this file type is a fifo. /// /// # Examples /// @@ -738,7 +738,7 @@ pub trait FileTypeExt { /// ``` #[stable(feature = "file_type_ext", since = "1.5.0")] fn is_fifo(&self) -> bool; - /// Returns whether this file type is a socket. + /// Returns `true` if this file type is a socket. /// /// # Examples /// @@ -805,9 +805,9 @@ impl DirEntryExt for fs::DirEntry { /// # Note /// /// On Windows, you must specify whether a symbolic link points to a file -/// or directory. Use `os::windows::fs::symlink_file` to create a +/// or directory. Use `os::windows::fs::symlink_file` to create a /// symbolic link to a file, or `os::windows::fs::symlink_dir` to create a -/// symbolic link to a directory. Additionally, the process must have +/// symbolic link to a directory. Additionally, the process must have /// `SeCreateSymbolicLinkPrivilege` in order to be able to create a /// symbolic link. /// diff --git a/src/libstd/sys/unix/ext/mod.rs b/src/libstd/sys/unix/ext/mod.rs index 36e9370b713..ccbac1a3e4b 100644 --- a/src/libstd/sys/unix/ext/mod.rs +++ b/src/libstd/sys/unix/ext/mod.rs @@ -1,4 +1,4 @@ -//! Experimental extensions to `std` for Unix platforms. +//! Platform-specific extensions to `std` for Unix platforms. //! //! Provides access to platform-level information on Unix platforms, and //! exposes Unix-specific functions that would otherwise be inappropriate as diff --git a/src/libstd/sys/unix/ext/net.rs b/src/libstd/sys/unix/ext/net.rs index a3ae5943f60..acc064acfcd 100644 --- a/src/libstd/sys/unix/ext/net.rs +++ b/src/libstd/sys/unix/ext/net.rs @@ -134,7 +134,7 @@ impl SocketAddr { }) } - /// Returns true if and only if the address is unnamed. + /// Returns `true` if the address is unnamed. /// /// # Examples /// @@ -516,7 +516,7 @@ impl UnixStream { /// ``` /// /// # Platform specific - /// On Redox this always returns None. + /// On Redox this always returns `None`. #[stable(feature = "unix_socket", since = "1.10.0")] pub fn take_error(&self) -> io::Result<Option<io::Error>> { self.0.take_error() @@ -841,7 +841,7 @@ impl UnixListener { /// ``` /// /// # Platform specific - /// On Redox this always returns None. + /// On Redox this always returns `None`. #[stable(feature = "unix_socket", since = "1.10.0")] pub fn take_error(&self) -> io::Result<Option<io::Error>> { self.0.take_error() @@ -1047,7 +1047,7 @@ impl UnixDatagram { Ok(UnixDatagram(inner)) } - /// Create an unnamed pair of connected sockets. + /// Creates an unnamed pair of connected sockets. /// /// Returns two `UnixDatagrams`s which are connected to each other. /// diff --git a/src/libstd/sys/unix/ext/process.rs b/src/libstd/sys/unix/ext/process.rs index 0282aaae909..2c5943fdac3 100644 --- a/src/libstd/sys/unix/ext/process.rs +++ b/src/libstd/sys/unix/ext/process.rs @@ -13,13 +13,13 @@ use sys_common::{AsInnerMut, AsInner, FromInner, IntoInner}; /// [`process::Command`]: ../../../../std/process/struct.Command.html #[stable(feature = "rust1", since = "1.0.0")] pub trait CommandExt { - /// Sets the child process's user id. This translates to a + /// Sets the child process's user ID. This translates to a /// `setuid` call in the child process. Failure in the `setuid` /// call will cause the spawn to fail. #[stable(feature = "rust1", since = "1.0.0")] fn uid(&mut self, id: u32) -> &mut process::Command; - /// Similar to `uid`, but sets the group id of the child process. This has + /// Similar to `uid`, but sets the group ID of the child process. This has /// the same semantics as the `uid` field. #[stable(feature = "rust1", since = "1.0.0")] fn gid(&mut self, id: u32) -> &mut process::Command; diff --git a/src/libstd/sys/unix/process/process_unix.rs b/src/libstd/sys/unix/process/process_unix.rs index f0f8032b4b5..12d3e9b13b1 100644 --- a/src/libstd/sys/unix/process/process_unix.rs +++ b/src/libstd/sys/unix/process/process_unix.rs @@ -383,7 +383,7 @@ impl Command { // Processes //////////////////////////////////////////////////////////////////////////////// -/// The unique id of the process (this should never be negative). +/// The unique ID of the process (this should never be negative). pub struct Process { pid: pid_t, status: Option<ExitStatus>, diff --git a/src/libstd/sys/unix/stdio.rs b/src/libstd/sys/unix/stdio.rs index 8a6b7b5f876..715f2eafb2d 100644 --- a/src/libstd/sys/unix/stdio.rs +++ b/src/libstd/sys/unix/stdio.rs @@ -12,7 +12,7 @@ impl Stdin { pub fn read(&self, data: &mut [u8]) -> io::Result<usize> { let fd = FileDesc::new(libc::STDIN_FILENO); let ret = fd.read(data); - fd.into_raw(); + fd.into_raw(); // do not close this FD ret } } @@ -23,7 +23,7 @@ impl Stdout { pub fn write(&self, data: &[u8]) -> io::Result<usize> { let fd = FileDesc::new(libc::STDOUT_FILENO); let ret = fd.write(data); - fd.into_raw(); + fd.into_raw(); // do not close this FD ret } @@ -38,7 +38,7 @@ impl Stderr { pub fn write(&self, data: &[u8]) -> io::Result<usize> { let fd = FileDesc::new(libc::STDERR_FILENO); let ret = fd.write(data); - fd.into_raw(); + fd.into_raw(); // do not close this FD ret } diff --git a/src/libstd/sys/windows/ext/ffi.rs b/src/libstd/sys/windows/ext/ffi.rs index eb278919307..6508c0cf447 100644 --- a/src/libstd/sys/windows/ext/ffi.rs +++ b/src/libstd/sys/windows/ext/ffi.rs @@ -3,19 +3,19 @@ //! # Overview //! //! For historical reasons, the Windows API uses a form of potentially -//! ill-formed UTF-16 encoding for strings. Specifically, the 16-bit +//! ill-formed UTF-16 encoding for strings. Specifically, the 16-bit //! code units in Windows strings may contain [isolated surrogate code -//! points which are not paired together][ill-formed-utf-16]. The +//! points which are not paired together][ill-formed-utf-16]. The //! Unicode standard requires that surrogate code points (those in the //! range U+D800 to U+DFFF) always be *paired*, because in the UTF-16 //! encoding a *surrogate code unit pair* is used to encode a single -//! character. For compatibility with code that does not enforce +//! character. For compatibility with code that does not enforce //! these pairings, Windows does not enforce them, either. //! //! While it is not always possible to convert such a string losslessly into //! a valid UTF-16 string (or even UTF-8), it is often desirable to be //! able to round-trip such a string from and to Windows APIs -//! losslessly. For example, some Rust code may be "bridging" some +//! losslessly. For example, some Rust code may be "bridging" some //! Windows APIs together, just passing `WCHAR` strings among those //! APIs without ever really looking into the strings. //! @@ -28,16 +28,16 @@ //! # `OsStringExt` and `OsStrExt` //! //! [`OsString`] is the Rust wrapper for owned strings in the -//! preferred representation of the operating system. On Windows, +//! preferred representation of the operating system. On Windows, //! this struct gets augmented with an implementation of the -//! [`OsStringExt`] trait, which has a [`from_wide`] method. This +//! [`OsStringExt`] trait, which has a [`from_wide`] method. This //! lets you create an [`OsString`] from a `&[u16]` slice; presumably //! you get such a slice out of a `WCHAR` Windows API. //! //! Similarly, [`OsStr`] is the Rust wrapper for borrowed strings from -//! preferred representation of the operating system. On Windows, the +//! preferred representation of the operating system. On Windows, the //! [`OsStrExt`] trait provides the [`encode_wide`] method, which -//! outputs an [`EncodeWide`] iterator. You can [`collect`] this +//! outputs an [`EncodeWide`] iterator. You can [`collect`] this //! iterator, for example, to obtain a `Vec<u16>`; you can later get a //! pointer to this vector's contents and feed it to Windows APIs. //! diff --git a/src/libstd/sys/windows/ext/fs.rs b/src/libstd/sys/windows/ext/fs.rs index 6342af46daf..89038da6295 100644 --- a/src/libstd/sys/windows/ext/fs.rs +++ b/src/libstd/sys/windows/ext/fs.rs @@ -441,10 +441,10 @@ impl MetadataExt for Metadata { /// [`FileType`]: ../../../../std/fs/struct.FileType.html #[unstable(feature = "windows_file_type_ext", issue = "0")] pub trait FileTypeExt { - /// Returns whether this file type is a symbolic link that is also a directory. + /// Returns `true` if this file type is a symbolic link that is also a directory. #[unstable(feature = "windows_file_type_ext", issue = "0")] fn is_symlink_dir(&self) -> bool; - /// Returns whether this file type is a symbolic link that is also a file. + /// Returns `true` if this file type is a symbolic link that is also a file. #[unstable(feature = "windows_file_type_ext", issue = "0")] fn is_symlink_file(&self) -> bool; } diff --git a/src/libstd/sys/windows/ext/io.rs b/src/libstd/sys/windows/ext/io.rs index 76143dee464..fbe0426ce5a 100644 --- a/src/libstd/sys/windows/ext/io.rs +++ b/src/libstd/sys/windows/ext/io.rs @@ -16,7 +16,7 @@ pub type RawHandle = raw::HANDLE; #[stable(feature = "rust1", since = "1.0.0")] pub type RawSocket = raw::SOCKET; -/// Extract raw handles. +/// Extracts raw handles. #[stable(feature = "rust1", since = "1.0.0")] pub trait AsRawHandle { /// Extracts the raw handle, without taking any ownership. @@ -98,7 +98,7 @@ impl IntoRawHandle for fs::File { } } -/// Extract raw sockets. +/// Extracts raw sockets. #[stable(feature = "rust1", since = "1.0.0")] pub trait AsRawSocket { /// Extracts the underlying raw socket from this object. @@ -106,7 +106,7 @@ pub trait AsRawSocket { fn as_raw_socket(&self) -> RawSocket; } -/// Create I/O objects from raw sockets. +/// Creates I/O objects from raw sockets. #[stable(feature = "from_raw_os", since = "1.1.0")] pub trait FromRawSocket { /// Creates a new I/O object from the given raw socket. diff --git a/src/libstd/sys/windows/os.rs b/src/libstd/sys/windows/os.rs index 5f478827b43..7399dd41a41 100644 --- a/src/libstd/sys/windows/os.rs +++ b/src/libstd/sys/windows/os.rs @@ -1,4 +1,4 @@ -//! Implementation of `std::os` functionality for Windows +//! Implementation of `std::os` functionality for Windows. #![allow(nonstandard_style)] diff --git a/src/libstd/sys/windows/pipe.rs b/src/libstd/sys/windows/pipe.rs index 0d9195a5c97..d3b102268f6 100644 --- a/src/libstd/sys/windows/pipe.rs +++ b/src/libstd/sys/windows/pipe.rs @@ -282,7 +282,7 @@ impl<'a> AsyncPipe<'a> { /// Takes a parameter `wait` which indicates if this pipe is currently being /// read whether the function should block waiting for the read to complete. /// - /// Return values: + /// Returns values: /// /// * `true` - finished any pending read and the pipe is not at EOF (keep /// going) diff --git a/src/libstd/sys/windows/stdio.rs b/src/libstd/sys/windows/stdio.rs index a4f4bd22cd9..0ea19a85525 100644 --- a/src/libstd/sys/windows/stdio.rs +++ b/src/libstd/sys/windows/stdio.rs @@ -188,7 +188,9 @@ impl Output { } fn invalid_encoding() -> io::Error { - io::Error::new(io::ErrorKind::InvalidData, "text was not valid unicode") + io::Error::new(io::ErrorKind::InvalidData, + "Windows stdio in console mode does not support non-UTF-8 byte sequences; \ + see https://github.com/rust-lang/rust/issues/23344") } fn readconsole_input_control(wakeup_mask: c::ULONG) -> c::CONSOLE_READCONSOLE_CONTROL { diff --git a/src/libstd/sys_common/backtrace.rs b/src/libstd/sys_common/backtrace.rs index 57f31cb726c..347244b0e0d 100644 --- a/src/libstd/sys_common/backtrace.rs +++ b/src/libstd/sys_common/backtrace.rs @@ -171,7 +171,7 @@ pub fn log_enabled() -> Option<PrintFormat> { val } -/// Print the symbol of the backtrace frame. +/// Prints the symbol of the backtrace frame. /// /// These output functions should now be used everywhere to ensure consistency. /// You may want to also use `output_fileline`. @@ -203,7 +203,7 @@ fn output(w: &mut dyn Write, idx: usize, frame: Frame, w.write_all(b"\n") } -/// Print the filename and line number of the backtrace frame. +/// Prints the filename and line number of the backtrace frame. /// /// See also `output`. #[allow(dead_code)] diff --git a/src/libstd/sys_common/wtf8.rs b/src/libstd/sys_common/wtf8.rs index 7f355fa7ec2..6d4594fe295 100644 --- a/src/libstd/sys_common/wtf8.rs +++ b/src/libstd/sys_common/wtf8.rs @@ -34,7 +34,7 @@ const UTF8_REPLACEMENT_CHARACTER: &str = "\u{FFFD}"; /// A Unicode code point: from U+0000 to U+10FFFF. /// -/// Compare with the `char` type, +/// Compares with the `char` type, /// which represents a Unicode scalar value: /// a code point that is not a surrogate (U+D800 to U+DFFF). #[derive(Eq, PartialEq, Ord, PartialOrd, Clone, Copy)] @@ -366,7 +366,7 @@ impl Wtf8Buf { } } -/// Create a new WTF-8 string from an iterator of code points. +/// Creates a new WTF-8 string from an iterator of code points. /// /// This replaces surrogate code point pairs with supplementary code points, /// like concatenating ill-formed UTF-16 strings effectively would. @@ -664,7 +664,7 @@ impl Wtf8 { } -/// Return a slice of the given string for the byte range [`begin`..`end`). +/// Returns a slice of the given string for the byte range [`begin`..`end`). /// /// # Panics /// @@ -686,7 +686,7 @@ impl ops::Index<ops::Range<usize>> for Wtf8 { } } -/// Return a slice of the given string from byte `begin` to its end. +/// Returns a slice of the given string from byte `begin` to its end. /// /// # Panics /// @@ -706,7 +706,7 @@ impl ops::Index<ops::RangeFrom<usize>> for Wtf8 { } } -/// Return a slice of the given string from its beginning to byte `end`. +/// Returns a slice of the given string from its beginning to byte `end`. /// /// # Panics /// diff --git a/src/libstd/thread/local.rs b/src/libstd/thread/local.rs index 5d2eb5f8e73..8207709e1f9 100644 --- a/src/libstd/thread/local.rs +++ b/src/libstd/thread/local.rs @@ -126,7 +126,8 @@ impl<T: 'static> fmt::Debug for LocalKey<T> { /// [`std::thread::LocalKey`]: ../std/thread/struct.LocalKey.html #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] -#[allow_internal_unstable] +#[cfg_attr(stage0, allow_internal_unstable)] +#[cfg_attr(not(stage0), allow_internal_unstable(thread_local_internals))] macro_rules! thread_local { // empty (base case for the recursion) () => {}; @@ -148,7 +149,10 @@ macro_rules! thread_local { reason = "should not be necessary", issue = "0")] #[macro_export] -#[allow_internal_unstable] +#[cfg_attr(stage0, allow_internal_unstable)] +#[cfg_attr(not(stage0), allow_internal_unstable( + thread_local_internals, cfg_target_thread_local, thread_local, +))] #[allow_internal_unsafe] macro_rules! __thread_local_inner { (@key $(#[$attr:meta])* $vis:vis $name:ident, $t:ty, $init:expr) => { diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index eb8e0c1c8ac..438ea3aa3f6 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -841,7 +841,7 @@ const NOTIFIED: usize = 2; /// let flag2 = Arc::clone(&flag); /// /// let parked_thread = thread::spawn(move || { -/// // We want to wait until the flag is set. We *could* just spin, but using +/// // We want to wait until the flag is set. We *could* just spin, but using /// // park/unpark is more efficient. /// while !flag2.load(Ordering::Acquire) { /// println!("Parking thread"); diff --git a/src/libstd/time.rs b/src/libstd/time.rs index 23924559fcc..c258e3f1a55 100644 --- a/src/libstd/time.rs +++ b/src/libstd/time.rs @@ -33,7 +33,7 @@ pub use core::time::{SECOND, MILLISECOND, MICROSECOND, NANOSECOND}; /// instant when created, and are often useful for tasks such as measuring /// benchmarks or timing how long an operation takes. /// -/// Note, however, that instants are not guaranteed to be **steady**. In other +/// Note, however, that instants are not guaranteed to be **steady**. In other /// words, each tick of the underlying clock may not be the same length (e.g. /// some seconds may be longer than others). An instant may jump forwards or /// experience time dilation (slow down or speed up), but it will never go |