From e7b0f2badf7c3393f1b36339b121054d05353442 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 12 Mar 2017 14:04:52 -0400 Subject: Remove function invokation parens from documentation links. This was never established as a convention we should follow in the 'More API Documentation Conventions' RFC: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md --- src/libstd/sync/barrier.rs | 4 ++-- src/libstd/sync/condvar.rs | 18 +++++++++--------- src/libstd/sync/mpsc/mod.rs | 12 ++++++------ src/libstd/sync/mutex.rs | 6 +++--- src/libstd/sync/rwlock.rs | 12 ++++++------ 5 files changed, 26 insertions(+), 26 deletions(-) (limited to 'src/libstd/sync') diff --git a/src/libstd/sync/barrier.rs b/src/libstd/sync/barrier.rs index f15e7ff8916..295a49d6a8e 100644 --- a/src/libstd/sync/barrier.rs +++ b/src/libstd/sync/barrier.rs @@ -52,10 +52,10 @@ struct BarrierState { /// A result returned from wait. /// -/// Currently this opaque structure only has one method, [`.is_leader()`]. Only +/// Currently this opaque structure only has one method, [`.is_leader`]. Only /// one thread will receive a result that will return `true` from this function. /// -/// [`.is_leader()`]: #method.is_leader +/// [`.is_leader`]: #method.is_leader /// /// # Examples /// diff --git a/src/libstd/sync/condvar.rs b/src/libstd/sync/condvar.rs index 68c7e88f67f..7ad9d9ee37c 100644 --- a/src/libstd/sync/condvar.rs +++ b/src/libstd/sync/condvar.rs @@ -150,7 +150,7 @@ impl Condvar { /// /// This function will atomically unlock the mutex specified (represented by /// `guard`) and block the current thread. This means that any calls - /// to [`notify_one()`] or [`notify_all()`] which happen logically after the + /// to [`notify_one`] or [`notify_all`] which happen logically after the /// mutex is unlocked are candidates to wake this thread up. When this /// function call returns, the lock specified will have been re-acquired. /// @@ -167,16 +167,16 @@ impl Condvar { /// /// # Panics /// - /// This function will [`panic!()`] if it is used with more than one mutex + /// This function will [`panic!`] if it is used with more than one mutex /// over time. Each condition variable is dynamically bound to exactly one /// mutex to ensure defined behavior across platforms. If this functionality /// is not desired, then unsafe primitives in `sys` are provided. /// - /// [`notify_one()`]: #method.notify_one - /// [`notify_all()`]: #method.notify_all + /// [`notify_one`]: #method.notify_one + /// [`notify_all`]: #method.notify_all /// [poisoning]: ../sync/struct.Mutex.html#poisoning /// [`Mutex`]: ../sync/struct.Mutex.html - /// [`panic!()`]: ../../std/macro.panic.html + /// [`panic!`]: ../../std/macro.panic.html /// /// # Examples /// @@ -359,11 +359,11 @@ impl Condvar { /// be woken up from its call to [`wait`] or [`wait_timeout`]. Calls to /// `notify_one` are not buffered in any way. /// - /// To wake up all threads, see [`notify_all()`]. + /// To wake up all threads, see [`notify_all`]. /// /// [`wait`]: #method.wait /// [`wait_timeout`]: #method.wait_timeout - /// [`notify_all()`]: #method.notify_all + /// [`notify_all`]: #method.notify_all /// /// # Examples /// @@ -401,9 +401,9 @@ impl Condvar { /// variable are awoken. Calls to `notify_all()` are not buffered in any /// way. /// - /// To wake up only one thread, see [`notify_one()`]. + /// To wake up only one thread, see [`notify_one`]. /// - /// [`notify_one()`]: #method.notify_one + /// [`notify_one`]: #method.notify_one /// /// # Examples /// diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs index aeeab170dea..71dd94161c0 100644 --- a/src/libstd/sync/mpsc/mod.rs +++ b/src/libstd/sync/mpsc/mod.rs @@ -460,10 +460,10 @@ impl UnsafeFlavor for Receiver { /// All data sent on the sender will become available on the receiver, and no /// send will block the calling thread (this channel has an "infinite buffer"). /// -/// If the [`Receiver`] is disconnected while trying to [`send()`] with the -/// [`Sender`], the [`send()`] method will return an error. +/// If the [`Receiver`] is disconnected while trying to [`send`] with the +/// [`Sender`], the [`send`] method will return an error. /// -/// [`send()`]: ../../../std/sync/mpsc/struct.Sender.html#method.send +/// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send /// [`Sender`]: ../../../std/sync/mpsc/struct.Sender.html /// [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html /// @@ -504,13 +504,13 @@ pub fn channel() -> (Sender, Receiver) { /// `bound` specifies the buffer size. When the internal buffer becomes full, /// future sends will *block* waiting for the buffer to open up. Note that a /// buffer size of 0 is valid, in which case this becomes "rendezvous channel" -/// where each [`send()`] will not return until a recv is paired with it. +/// where each [`send`] will not return until a recv is paired with it. /// /// Like asynchronous channels, if the [`Receiver`] is disconnected while -/// trying to [`send()`] with the [`SyncSender`], the [`send()`] method will +/// trying to [`send`] with the [`SyncSender`], the [`send`] method will /// return an error. /// -/// [`send()`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.send +/// [`send`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.send /// [`SyncSender`]: ../../../std/sync/mpsc/struct.SyncSender.html /// [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html /// diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs index 97b84d59218..48d8d34dbe0 100644 --- a/src/libstd/sync/mutex.rs +++ b/src/libstd/sync/mutex.rs @@ -135,13 +135,13 @@ unsafe impl Sync for Mutex { } /// The data protected by the mutex can be access through this guard via its /// [`Deref`] and [`DerefMut`] implementations. /// -/// This structure is created by the [`lock()`] and [`try_lock()`] methods on +/// This structure is created by the [`lock`] and [`try_lock`] methods on /// [`Mutex`]. /// /// [`Deref`]: ../../std/ops/trait.Deref.html /// [`DerefMut`]: ../../std/ops/trait.DerefMut.html -/// [`lock()`]: struct.Mutex.html#method.lock -/// [`try_lock()`]: struct.Mutex.html#method.try_lock +/// [`lock`]: struct.Mutex.html#method.lock +/// [`try_lock`]: struct.Mutex.html#method.try_lock /// [`Mutex`]: struct.Mutex.html #[must_use] #[stable(feature = "rust1", since = "1.0.0")] diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs index a3db0adeda0..d26f2f7bb7e 100644 --- a/src/libstd/sync/rwlock.rs +++ b/src/libstd/sync/rwlock.rs @@ -78,11 +78,11 @@ unsafe impl Sync for RwLock {} /// RAII structure used to release the shared read access of a lock when /// dropped. /// -/// This structure is created by the [`read()`] and [`try_read()`] methods on +/// This structure is created by the [`read`] and [`try_read`] methods on /// [`RwLock`]. /// -/// [`read()`]: struct.RwLock.html#method.read -/// [`try_read()`]: struct.RwLock.html#method.try_read +/// [`read`]: struct.RwLock.html#method.read +/// [`try_read`]: struct.RwLock.html#method.try_read /// [`RwLock`]: struct.RwLock.html #[must_use] #[stable(feature = "rust1", since = "1.0.0")] @@ -96,11 +96,11 @@ impl<'a, T: ?Sized> !marker::Send for RwLockReadGuard<'a, T> {} /// RAII structure used to release the exclusive write access of a lock when /// dropped. /// -/// This structure is created by the [`write()`] and [`try_write()`] methods +/// This structure is created by the [`write`] and [`try_write`] methods /// on [`RwLock`]. /// -/// [`write()`]: struct.RwLock.html#method.write -/// [`try_write()`]: struct.RwLock.html#method.try_write +/// [`write`]: struct.RwLock.html#method.write +/// [`try_write`]: struct.RwLock.html#method.try_write /// [`RwLock`]: struct.RwLock.html #[must_use] #[stable(feature = "rust1", since = "1.0.0")] -- cgit 1.4.1-3-g733a5 From ec8ecf4f9d06f7e034180a6c56f33a6f800dd1e2 Mon Sep 17 00:00:00 2001 From: ScottAbbey Date: Fri, 17 Mar 2017 13:27:13 -0500 Subject: Fix typo in mutex.rs docs This seems to match other uses of "be accessed" in the document. --- src/libstd/sync/mutex.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd/sync') diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs index 97b84d59218..483d0ef752d 100644 --- a/src/libstd/sync/mutex.rs +++ b/src/libstd/sync/mutex.rs @@ -132,7 +132,7 @@ unsafe impl Sync for Mutex { } /// An RAII implementation of a "scoped lock" of a mutex. When this structure is /// dropped (falls out of scope), the lock will be unlocked. /// -/// The data protected by the mutex can be access through this guard via its +/// The data protected by the mutex can be accessed through this guard via its /// [`Deref`] and [`DerefMut`] implementations. /// /// This structure is created by the [`lock()`] and [`try_lock()`] methods on -- cgit 1.4.1-3-g733a5 From 3207657d12951df71c30f6e5e26e2f70f7b07d2e Mon Sep 17 00:00:00 2001 From: projektir Date: Mon, 27 Mar 2017 16:10:44 -0400 Subject: Adding linking for Once docs #29377 --- src/libstd/sync/once.rs | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) (limited to 'src/libstd/sync') diff --git a/src/libstd/sync/once.rs b/src/libstd/sync/once.rs index 1e7394c0b09..d9edf5d1254 100644 --- a/src/libstd/sync/once.rs +++ b/src/libstd/sync/once.rs @@ -72,9 +72,11 @@ use thread::{self, Thread}; /// A synchronization primitive which can be used to run a one-time global /// initialization. Useful for one-time initialization for FFI or related -/// functionality. This type can only be constructed with the `ONCE_INIT` +/// functionality. This type can only be constructed with the [`ONCE_INIT`] /// value. /// +/// [`ONCE_INIT`]: constant.ONCE_INIT.html +/// /// # Examples /// /// ``` @@ -101,15 +103,28 @@ unsafe impl Sync for Once {} #[stable(feature = "rust1", since = "1.0.0")] unsafe impl Send for Once {} -/// State yielded to the `call_once_force` method which can be used to query -/// whether the `Once` was previously poisoned or not. +/// State yielded to the [`call_once_force`] method which can be used to query +/// whether the [`Once`] was previously poisoned or not. +/// +/// [`call_once_force`]: struct.Once.html#method.call_once_force +/// [`Once`]: struct.Once.html #[unstable(feature = "once_poison", issue = "33577")] #[derive(Debug)] pub struct OnceState { poisoned: bool, } -/// Initialization value for static `Once` values. +/// Initialization value for static [`Once`] values. +/// +/// [`Once`]: struct.Once.html +/// +/// # Examples +/// +/// ``` +/// use std::sync::{Once, ONCE_INIT}; +/// +/// static START: Once = ONCE_INIT; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const ONCE_INIT: Once = Once::new(); @@ -212,15 +227,19 @@ impl Once { self.call_inner(false, &mut |_| f.take().unwrap()()); } - /// Performs the same function as `call_once` except ignores poisoning. + /// Performs the same function as [`call_once`] except ignores poisoning. + /// + /// [`call_once`]: struct.Once.html#method.call_once /// /// If this `Once` has been poisoned (some initialization panicked) then /// this function will continue to attempt to call initialization functions /// until one of them doesn't panic. /// - /// The closure `f` is yielded a structure which can be used to query the + /// The closure `f` is yielded a [`OnceState`] structure which can be used to query the /// state of this `Once` (whether initialization has previously panicked or /// not). + /// + /// [`OnceState`]: struct.OnceState.html #[unstable(feature = "once_poison", issue = "33577")] pub fn call_once_force(&'static self, f: F) where F: FnOnce(&OnceState) { // same as above, just with a different parameter to `call_inner`. @@ -366,10 +385,12 @@ impl Drop for Finish { } impl OnceState { - /// Returns whether the associated `Once` has been poisoned. + /// Returns whether the associated [`Once`] has been poisoned. /// - /// Once an initalization routine for a `Once` has panicked it will forever + /// Once an initalization routine for a [`Once`] has panicked it will forever /// indicate to future forced initialization routines that it is poisoned. + /// + /// [`Once`]: struct.Once.html #[unstable(feature = "once_poison", issue = "33577")] pub fn poisoned(&self) -> bool { self.poisoned -- cgit 1.4.1-3-g733a5 From 5a6ebdfcda149fdf3093003bceacbb2e0a1682ab Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Thu, 30 Mar 2017 23:27:09 -0700 Subject: Add links to std::sync::mpsc docs #29377 --- src/libstd/sync/mpsc/mod.rs | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) (limited to 'src/libstd/sync') diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs index 71dd94161c0..288a589e589 100644 --- a/src/libstd/sync/mpsc/mod.rs +++ b/src/libstd/sync/mpsc/mod.rs @@ -13,40 +13,50 @@ //! This module provides message-based communication over channels, concretely //! defined among three types: //! -//! * `Sender` -//! * `SyncSender` -//! * `Receiver` +//! * [`Sender`] +//! * [`SyncSender`] +//! * [`Receiver`] //! -//! A `Sender` or `SyncSender` is used to send data to a `Receiver`. Both +//! A [`Sender`] or [`SyncSender`] is used to send data to a [`Receiver`]. Both //! senders are clone-able (multi-producer) such that many threads can send //! simultaneously to one receiver (single-consumer). //! //! These channels come in two flavors: //! -//! 1. An asynchronous, infinitely buffered channel. The `channel()` function +//! 1. An asynchronous, infinitely buffered channel. The [`channel()`] function //! will return a `(Sender, Receiver)` tuple where all sends will be //! **asynchronous** (they never block). The channel conceptually has an //! infinite buffer. //! -//! 2. A synchronous, bounded channel. The `sync_channel()` function will return -//! a `(SyncSender, Receiver)` tuple where the storage for pending messages -//! is a pre-allocated buffer of a fixed size. All sends will be +//! 2. A synchronous, bounded channel. The [`sync_channel()`] function will +//! return a `(SyncSender, Receiver)` tuple where the storage for pending +//! messages is a pre-allocated buffer of a fixed size. All sends will be //! **synchronous** by blocking until there is buffer space available. Note -//! that a bound of 0 is allowed, causing the channel to become a -//! "rendezvous" channel where each sender atomically hands off a message to -//! a receiver. +//! that a bound of 0 is allowed, causing the channel to become a "rendezvous" +//! channel where each sender atomically hands off a message to a receiver. +//! +//! [`Sender`]: ../../../std/sync/mpsc/struct.Sender.html +//! [`SyncSender`]: ../../../std/sync/mpsc/struct.SyncSender.html +//! [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html +//! [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send +//! [`channel()`]: ../../../std/sync/mpsc/fn.channel.html +//! [`sync_channel()`]: ../../../std/sync/mpsc/fn.sync_channel.html //! //! ## Disconnection //! -//! The send and receive operations on channels will all return a `Result` +//! The send and receive operations on channels will all return a [`Result`] //! indicating whether the operation succeeded or not. An unsuccessful operation //! is normally indicative of the other half of a channel having "hung up" by //! being dropped in its corresponding thread. //! //! Once half of a channel has been deallocated, most operations can no longer -//! continue to make progress, so `Err` will be returned. Many applications will -//! continue to `unwrap()` the results returned from this module, instigating a -//! propagation of failure among threads if one unexpectedly dies. +//! continue to make progress, so [`Err`] will be returned. Many applications +//! will continue to [`unwrap()`] the results returned from this module, +//! instigating a propagation of failure among threads if one unexpectedly dies. +//! +//! [`Result`]: ../../../std/result/enum.Result.html +//! [`Err`]: ../../../std/result/enum.Result.html#variant.Err +//! [`unwrap()`]: ../../../std/result/enum.Result.html#method.unwrap //! //! # Examples //! -- cgit 1.4.1-3-g733a5 From 44d8b236f4da3b17bc4a7ac3d571d67acd3be020 Mon Sep 17 00:00:00 2001 From: projektir Date: Fri, 31 Mar 2017 18:58:32 -0400 Subject: Updating the description for BarrierWaitResult #29377 --- src/libstd/sync/barrier.rs | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'src/libstd/sync') diff --git a/src/libstd/sync/barrier.rs b/src/libstd/sync/barrier.rs index 295a49d6a8e..a7b01e49d2b 100644 --- a/src/libstd/sync/barrier.rs +++ b/src/libstd/sync/barrier.rs @@ -50,12 +50,11 @@ struct BarrierState { generation_id: usize, } -/// A result returned from wait. +/// A `BarrierWaitResult` is returned by [`wait`] when all threads in the [`Barrier`] +/// have rendezvoused. /// -/// Currently this opaque structure only has one method, [`.is_leader`]. Only -/// one thread will receive a result that will return `true` from this function. -/// -/// [`.is_leader`]: #method.is_leader +/// [`wait`]: struct.Barrier.html#method.wait +/// [`Barrier`]: struct.Barrier.html /// /// # Examples /// -- cgit 1.4.1-3-g733a5 From 89c35ae76493b6ea2401d2f0271f0f35693b1198 Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Fri, 31 Mar 2017 17:05:45 -0700 Subject: Add links and examples to std::sync::mpsc docs (#29377) This change adds links to to `Receiver`, `Iter`, `TryIter`, `IntoIter`, `Sender`, `SyncSender`, `SendError`, `RecvError`, `TryRecvError`, `RecvTimeoutError`, `TrySendError`, `Sender::send`, `SyncSender::send`, `SyncSender::try_send`, `Receiver::recv`, `Receiver::recv_timeout`, `Receiver::iter`, and `Receiver::try_iter`. Examples added to `Receiver`, `Sender`, `Receiver::iter`. --- src/libstd/sync/mpsc/mod.rs | 167 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 136 insertions(+), 31 deletions(-) (limited to 'src/libstd/sync') diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs index 288a589e589..fa31c6cedd2 100644 --- a/src/libstd/sync/mpsc/mod.rs +++ b/src/libstd/sync/mpsc/mod.rs @@ -298,7 +298,28 @@ mod mpsc_queue; mod spsc_queue; /// The receiving-half of Rust's channel type. This half can only be owned by -/// one thread +/// one thread. +/// +/// Messages sent to the channel can be retrieved using [`recv`]. +/// +/// [`recv`]: ../../../std/sync/mpsc/struct.Receiver.html#method.recv +/// +/// # Examples +/// +/// ```rust +/// use std::sync::mpsc::channel; +/// use std::thread; +/// use std::time::Duration; +/// let (send, recv) = channel(); +/// thread::spawn(move || { +/// send.send("Hello world!"); +/// thread::sleep(Duration::from_secs(2)); // block for two seconds +/// send.send("Delayed for 2 seconds"); +/// }); +/// println!("{:?}", recv.recv()); // Received immediately +/// println!("Waiting..."); +/// println!("{:?}", recv.recv()); // Received after 2 seconds +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub struct Receiver { inner: UnsafeCell>, @@ -312,9 +333,12 @@ unsafe impl Send for Receiver { } #[stable(feature = "rust1", since = "1.0.0")] impl !Sync for Receiver { } -/// An iterator over messages on a receiver, this iterator will block -/// whenever `next` is called, waiting for a new message, and `None` will be -/// returned when the corresponding channel has hung up. +/// An iterator over messages on a receiver, this iterator will block whenever +/// [`next`] is called, waiting for a new message, and [`None`] will be returned +/// when the corresponding channel has hung up. +/// +/// [`next`]: ../../../std/iter/trait.Iterator.html#method.next +/// [`None`]: ../../../std/option/enum.Option.html#variant.None #[stable(feature = "rust1", since = "1.0.0")] #[derive(Debug)] pub struct Iter<'a, T: 'a> { @@ -322,11 +346,13 @@ pub struct Iter<'a, T: 'a> { } /// An iterator that attempts to yield all pending values for a receiver. -/// `None` will be returned when there are no pending values remaining or -/// if the corresponding channel has hung up. +/// [`None`] will be returned when there are no pending values remaining or if +/// the corresponding channel has hung up. /// /// This Iterator will never block the caller in order to wait for data to -/// become available. Instead, it will return `None`. +/// become available. Instead, it will return [`None`]. +/// +/// [`None`]: ../../../std/option/enum.Option.html#variant.None #[stable(feature = "receiver_try_iter", since = "1.15.0")] #[derive(Debug)] pub struct TryIter<'a, T: 'a> { @@ -334,8 +360,12 @@ pub struct TryIter<'a, T: 'a> { } /// An owning iterator over messages on a receiver, this iterator will block -/// whenever `next` is called, waiting for a new message, and `None` will be +/// whenever [`next`] is called, waiting for a new message, and [`None`] will be /// returned when the corresponding channel has hung up. +/// +/// [`next`]: ../../../std/iter/trait.Iterator.html#method.next +/// [`None`]: ../../../std/option/enum.Option.html#variant.None +/// #[stable(feature = "receiver_into_iter", since = "1.1.0")] #[derive(Debug)] pub struct IntoIter { @@ -344,6 +374,30 @@ pub struct IntoIter { /// The sending-half of Rust's asynchronous channel type. This half can only be /// owned by one thread, but it can be cloned to send to other threads. +/// +/// Messages can be sent through this channel with [`send`]. +/// +/// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send +/// +/// # Examples +/// +/// ```rust +/// use std::sync::mpsc::channel; +/// use std::thread; +/// let (sender, receiver) = channel(); +/// let sender2 = sender.clone(); +/// // First thread owns sender +/// thread::spawn(move || { +/// sender.send(1); +/// }); +/// // Second thread owns sender2 +/// thread::spawn(move || { +/// sender2.send(2); +/// }); +/// let msg = receiver.recv().unwrap(); +/// let msg2 = receiver.recv().unwrap(); +/// assert_eq!(3, msg + msg2); +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub struct Sender { inner: UnsafeCell>, @@ -359,6 +413,10 @@ impl !Sync for Sender { } /// The sending-half of Rust's synchronous channel type. This half can only be /// owned by one thread, but it can be cloned to send to other threads. +/// +/// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send +/// [`SyncSender::send`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.send +/// #[stable(feature = "rust1", since = "1.0.0")] pub struct SyncSender { inner: Arc>, @@ -370,25 +428,32 @@ unsafe impl Send for SyncSender {} #[stable(feature = "rust1", since = "1.0.0")] impl !Sync for SyncSender {} -/// An error returned from the `send` function on channels. +/// An error returned from the [`send`] function on channels. /// -/// A `send` operation can only fail if the receiving end of a channel is +/// A [`send`] operation can only fail if the receiving end of a channel is /// disconnected, implying that the data could never be received. The error /// contains the data being sent as a payload so it can be recovered. +/// +/// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send #[stable(feature = "rust1", since = "1.0.0")] #[derive(PartialEq, Eq, Clone, Copy)] pub struct SendError(#[stable(feature = "rust1", since = "1.0.0")] pub T); -/// An error returned from the `recv` function on a `Receiver`. +/// An error returned from the [`recv`] function on a [`Receiver`]. /// -/// The `recv` operation can only fail if the sending half of a channel is +/// The [`recv`] operation can only fail if the sending half of a channel is /// disconnected, implying that no further messages will ever be received. +/// +/// [`recv`]: ../../../std/sync/mpsc/struct.Receiver.html#method.recv +/// [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html #[derive(PartialEq, Eq, Clone, Copy, Debug)] #[stable(feature = "rust1", since = "1.0.0")] pub struct RecvError; -/// This enumeration is the list of the possible reasons that `try_recv` could +/// This enumeration is the list of the possible reasons that [`try_recv`] could /// not return data when called. +/// +/// [`try_recv`]: ../../../std/sync/mpsc/struct.Receiver.html#method.try_recv #[derive(PartialEq, Eq, Clone, Copy, Debug)] #[stable(feature = "rust1", since = "1.0.0")] pub enum TryRecvError { @@ -403,8 +468,10 @@ pub enum TryRecvError { Disconnected, } -/// This enumeration is the list of possible errors that `recv_timeout` could +/// This enumeration is the list of possible errors that [`recv_timeout`] could /// not return data when called. +/// +/// [`recv_timeout`]: ../../../std/sync/mpsc/struct.Receiver.html#method.recv_timeout #[derive(PartialEq, Eq, Clone, Copy, Debug)] #[stable(feature = "mpsc_recv_timeout", since = "1.12.0")] pub enum RecvTimeoutError { @@ -419,7 +486,9 @@ pub enum RecvTimeoutError { } /// This enumeration is the list of the possible error outcomes for the -/// `SyncSender::try_send` method. +/// [`SyncSender::try_send`] method. +/// +/// [`SyncSender::try_send`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.try_send #[stable(feature = "rust1", since = "1.0.0")] #[derive(PartialEq, Eq, Clone, Copy)] pub enum TrySendError { @@ -566,10 +635,13 @@ impl Sender { /// A successful send occurs when it is determined that the other end of /// the channel has not hung up already. An unsuccessful send would be one /// 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 + /// 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 - /// hang up immediately after this function returns `Ok`. + /// hang up immediately after this function returns [`Ok`]. + /// + /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err + /// [`Ok`]: ../../../std/result/enum.Result.html#variant.Ok /// /// This method will never block the current thread. /// @@ -712,9 +784,12 @@ impl SyncSender { /// time. If the buffer size is 0, however, it can be guaranteed that the /// receiver has indeed received the data if this function returns success. /// - /// This function will never panic, but it may return `Err` if the - /// `Receiver` has disconnected and is no longer able to receive + /// This function will never panic, but it may return [`Err`] if the + /// [`Receiver`] has disconnected and is no longer able to receive /// information. + /// + /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err + /// [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html #[stable(feature = "rust1", since = "1.0.0")] pub fn send(&self, t: T) -> Result<(), SendError> { self.inner.send(t).map_err(SendError) @@ -722,13 +797,16 @@ impl SyncSender { /// Attempts to send a value on this channel without blocking. /// - /// This method differs from `send` by returning immediately if the + /// This method differs from [`send`] by returning immediately if the /// channel's buffer is full or no receiver is waiting to acquire some - /// data. Compared with `send`, this function has two failure cases + /// data. Compared with [`send`], this function has two failure cases /// instead of one (one for disconnection, one for a full buffer). /// - /// See `SyncSender::send` for notes about guarantees of whether the + /// See [`SyncSender::send`] for notes about guarantees of whether the /// receiver has received the data or not if this function is successful. + /// + /// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send + /// [`SyncSender::send`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.send #[stable(feature = "rust1", since = "1.0.0")] pub fn try_send(&self, t: T) -> Result<(), TrySendError> { self.inner.try_send(t) @@ -829,15 +907,18 @@ impl Receiver { /// /// This function will always block the current thread if there is no data /// available and it's possible for more data to be sent. Once a message is - /// sent to the corresponding `Sender`, then this receiver will wake up and + /// sent to the corresponding [`Sender`], then this receiver will wake up and /// return that message. /// - /// If the corresponding `Sender` has disconnected, or it disconnects while - /// this call is blocking, this call will wake up and return `Err` to + /// If the corresponding [`Sender`] has disconnected, or it disconnects while + /// this call is blocking, this call will wake up and return [`Err`] to /// indicate that no more messages can ever be received on this channel. /// However, since channels are buffered, messages sent before the disconnect /// will still be properly received. /// + /// [`Sender`]: ../../../std/sync/mpsc/struct.Sender.html + /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err + /// /// # Examples /// /// ``` @@ -917,15 +998,18 @@ impl Receiver { /// /// This function will always block the current thread if there is no data /// available and it's possible for more data to be sent. Once a message is - /// sent to the corresponding `Sender`, then this receiver will wake up and + /// sent to the corresponding [`Sender`], then this receiver will wake up and /// return that message. /// - /// If the corresponding `Sender` has disconnected, or it disconnects while - /// this call is blocking, this call will wake up and return `Err` to + /// If the corresponding [`Sender`] has disconnected, or it disconnects while + /// this call is blocking, this call will wake up and return [`Err`] to /// indicate that no more messages can ever be received on this channel. /// However, since channels are buffered, messages sent before the disconnect /// will still be properly received. /// + /// [`Sender`]: ../../../std/sync/mpsc/struct.Sender.html + /// [`Err`]: ../../../std/result/enum.Result.html#variant.Err + /// /// # Examples /// /// ```no_run @@ -1003,7 +1087,26 @@ impl Receiver { } /// Returns an iterator that will block waiting for messages, but never - /// `panic!`. It will return `None` when the channel has hung up. + /// [`panic!`]. It will return [`None`] when the channel has hung up. + /// + /// [`panic!`]: ../../../std/macro.panic.html + /// [`None`]: ../../../std/option/enum.Option.html#variant.None + /// + /// # Examples + /// + /// ```rust + /// use std::sync::mpsc::channel; + /// use std::thread; + /// let (send, recv) = channel(); + /// thread::spawn(move || { + /// send.send(1u8); + /// send.send(2u8); + /// send.send(3u8); + /// }); + /// for x in recv.iter() { + /// println!("Got: {}", x); + /// } + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn iter(&self) -> Iter { Iter { rx: self } @@ -1011,8 +1114,10 @@ impl Receiver { /// Returns an iterator that will attempt to yield all pending values. /// It will return `None` if there are no more pending values or if the - /// channel has hung up. The iterator will never `panic!` or block the + /// channel has hung up. The iterator will never [`panic!`] or block the /// user by waiting for values. + /// + /// [`panic!`]: ../../../std/macro.panic.html #[stable(feature = "receiver_try_iter", since = "1.15.0")] pub fn try_iter(&self) -> TryIter { TryIter { rx: self } -- cgit 1.4.1-3-g733a5 From ae8ba78e9df9891c4a6ebedf87dfcdafcacc6e68 Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Fri, 31 Mar 2017 18:51:37 -0700 Subject: Fix broken links to std::iter::Iterator::next --- src/libstd/sync/mpsc/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd/sync') diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs index fa31c6cedd2..4f3d3422fd2 100644 --- a/src/libstd/sync/mpsc/mod.rs +++ b/src/libstd/sync/mpsc/mod.rs @@ -337,7 +337,7 @@ impl !Sync for Receiver { } /// [`next`] is called, waiting for a new message, and [`None`] will be returned /// when the corresponding channel has hung up. /// -/// [`next`]: ../../../std/iter/trait.Iterator.html#method.next +/// [`next`]: ../../../std/iter/trait.Iterator.html#tymethod.next /// [`None`]: ../../../std/option/enum.Option.html#variant.None #[stable(feature = "rust1", since = "1.0.0")] #[derive(Debug)] @@ -363,7 +363,7 @@ pub struct TryIter<'a, T: 'a> { /// whenever [`next`] is called, waiting for a new message, and [`None`] will be /// returned when the corresponding channel has hung up. /// -/// [`next`]: ../../../std/iter/trait.Iterator.html#method.next +/// [`next`]: ../../../std/iter/trait.Iterator.html#tymethod.next /// [`None`]: ../../../std/option/enum.Option.html#variant.None /// #[stable(feature = "receiver_into_iter", since = "1.1.0")] -- cgit 1.4.1-3-g733a5 From dab8e8121f4a2ba6322417ba7644f3a06973a785 Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Fri, 31 Mar 2017 23:22:59 -0700 Subject: Fix warnings in examples --- src/libstd/sync/mpsc/mod.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'src/libstd/sync') diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs index 4f3d3422fd2..33ffd5548fb 100644 --- a/src/libstd/sync/mpsc/mod.rs +++ b/src/libstd/sync/mpsc/mod.rs @@ -312,13 +312,13 @@ mod spsc_queue; /// use std::time::Duration; /// let (send, recv) = channel(); /// thread::spawn(move || { -/// send.send("Hello world!"); +/// send.send("Hello world!").unwrap(); /// thread::sleep(Duration::from_secs(2)); // block for two seconds -/// send.send("Delayed for 2 seconds"); +/// send.send("Delayed for 2 seconds").unwrap(); /// }); -/// println!("{:?}", recv.recv()); // Received immediately +/// println!("{}", recv.recv().unwrap()); // Received immediately /// println!("Waiting..."); -/// println!("{:?}", recv.recv()); // Received after 2 seconds +/// println!("{}", recv.recv().unwrap()); // Received after 2 seconds /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub struct Receiver { @@ -388,11 +388,11 @@ pub struct IntoIter { /// let sender2 = sender.clone(); /// // First thread owns sender /// thread::spawn(move || { -/// sender.send(1); +/// sender.send(1).unwrap(); /// }); /// // Second thread owns sender2 /// thread::spawn(move || { -/// sender2.send(2); +/// sender2.send(2).unwrap(); /// }); /// let msg = receiver.recv().unwrap(); /// let msg2 = receiver.recv().unwrap(); @@ -1099,9 +1099,9 @@ impl Receiver { /// use std::thread; /// let (send, recv) = channel(); /// thread::spawn(move || { - /// send.send(1u8); - /// send.send(2u8); - /// send.send(3u8); + /// send.send(1u8).unwrap(); + /// send.send(2u8).unwrap(); + /// send.send(3u8).unwrap(); /// }); /// for x in recv.iter() { /// println!("Got: {}", x); -- cgit 1.4.1-3-g733a5 From e7c2160f8a36468c38a0c4d9fb2a71bd6c4fefd8 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Fri, 17 Mar 2017 18:32:17 +0100 Subject: Fix mutex's docs inconsistency --- src/libstd/sync/mutex.rs | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'src/libstd/sync') diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs index d79be2944c9..f2c178a1ad5 100644 --- a/src/libstd/sync/mutex.rs +++ b/src/libstd/sync/mutex.rs @@ -30,7 +30,7 @@ use sys_common::poison::{self, TryLockError, TryLockResult, LockResult}; /// /// The mutexes in this module implement a strategy called "poisoning" where a /// mutex is considered poisoned whenever a thread panics while holding the -/// lock. Once a mutex is poisoned, all other threads are unable to access the +/// mutex. Once a mutex is poisoned, all other threads are unable to access the /// data by default as it is likely tainted (some invariant is not being /// upheld). /// @@ -115,7 +115,7 @@ pub struct Mutex { // Note that this mutex is in a *box*, not inlined into the struct itself. // Once a native mutex has been used once, its address can never change (it // can't be moved). This mutex type can be safely moved at any time, so to - // ensure that the native mutex is used correctly we box the inner lock to + // ensure that the native mutex is used correctly we box the inner mutex to // give it a constant address. inner: Box, poison: poison::Flag, @@ -183,7 +183,7 @@ impl Mutex { /// Acquires a mutex, blocking the current thread until it is able to do so. /// /// This function will block the local thread until it is available to acquire - /// the mutex. Upon returning, the thread is the only thread with the mutex + /// the mutex. Upon returning, the thread is the only thread with the lock /// held. An RAII guard is returned to allow scoped unlock of the lock. When /// the guard goes out of scope, the mutex will be unlocked. /// @@ -267,9 +267,9 @@ impl Mutex { } } - /// Determines whether the lock is poisoned. + /// Determines whether the mutex is poisoned. /// - /// If another thread is active, the lock can still become poisoned at any + /// If another thread is active, the mutex can still become poisoned at any /// time. You should not trust a `false` value for program correctness /// without additional synchronization. /// @@ -312,7 +312,7 @@ impl Mutex { #[stable(feature = "mutex_into_inner", since = "1.6.0")] pub fn into_inner(self) -> LockResult where T: Sized { // We know statically that there are no outstanding references to - // `self` so there's no need to lock the inner lock. + // `self` so there's no need to lock the inner mutex. // // To get the inner value, we'd like to call `data.into_inner()`, // but because `Mutex` impl-s `Drop`, we can't move out of it, so @@ -353,7 +353,7 @@ impl Mutex { #[stable(feature = "mutex_get_mut", since = "1.6.0")] pub fn get_mut(&mut self) -> LockResult<&mut T> { // We know statically that there are no other references to `self`, so - // there's no need to lock the inner lock. + // there's no need to lock the inner mutex. let data = unsafe { &mut *self.data.get() }; poison::map_result(self.poison.borrow(), |_| data ) } -- cgit 1.4.1-3-g733a5 From ab4f4428e778d45e0e8db2a254e55f5ec786410c Mon Sep 17 00:00:00 2001 From: Bryan Tan Date: Mon, 3 Apr 2017 16:09:19 -0700 Subject: Fix styling issues --- src/libstd/sync/mpsc/mod.rs | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'src/libstd/sync') diff --git a/src/libstd/sync/mpsc/mod.rs b/src/libstd/sync/mpsc/mod.rs index 33ffd5548fb..0da65a4f2e1 100644 --- a/src/libstd/sync/mpsc/mod.rs +++ b/src/libstd/sync/mpsc/mod.rs @@ -23,12 +23,12 @@ //! //! These channels come in two flavors: //! -//! 1. An asynchronous, infinitely buffered channel. The [`channel()`] function +//! 1. An asynchronous, infinitely buffered channel. The [`channel`] function //! will return a `(Sender, Receiver)` tuple where all sends will be //! **asynchronous** (they never block). The channel conceptually has an //! infinite buffer. //! -//! 2. A synchronous, bounded channel. The [`sync_channel()`] function will +//! 2. A synchronous, bounded channel. The [`sync_channel`] function will //! return a `(SyncSender, Receiver)` tuple where the storage for pending //! messages is a pre-allocated buffer of a fixed size. All sends will be //! **synchronous** by blocking until there is buffer space available. Note @@ -39,8 +39,8 @@ //! [`SyncSender`]: ../../../std/sync/mpsc/struct.SyncSender.html //! [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html //! [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send -//! [`channel()`]: ../../../std/sync/mpsc/fn.channel.html -//! [`sync_channel()`]: ../../../std/sync/mpsc/fn.sync_channel.html +//! [`channel`]: ../../../std/sync/mpsc/fn.channel.html +//! [`sync_channel`]: ../../../std/sync/mpsc/fn.sync_channel.html //! //! ## Disconnection //! @@ -51,12 +51,12 @@ //! //! Once half of a channel has been deallocated, most operations can no longer //! continue to make progress, so [`Err`] will be returned. Many applications -//! will continue to [`unwrap()`] the results returned from this module, +//! will continue to [`unwrap`] the results returned from this module, //! instigating a propagation of failure among threads if one unexpectedly dies. //! //! [`Result`]: ../../../std/result/enum.Result.html //! [`Err`]: ../../../std/result/enum.Result.html#variant.Err -//! [`unwrap()`]: ../../../std/result/enum.Result.html#method.unwrap +//! [`unwrap`]: ../../../std/result/enum.Result.html#method.unwrap //! //! # Examples //! @@ -310,12 +310,15 @@ mod spsc_queue; /// use std::sync::mpsc::channel; /// use std::thread; /// use std::time::Duration; +/// /// let (send, recv) = channel(); +/// /// thread::spawn(move || { /// send.send("Hello world!").unwrap(); /// thread::sleep(Duration::from_secs(2)); // block for two seconds /// send.send("Delayed for 2 seconds").unwrap(); /// }); +/// /// println!("{}", recv.recv().unwrap()); // Received immediately /// println!("Waiting..."); /// println!("{}", recv.recv().unwrap()); // Received after 2 seconds @@ -384,18 +387,23 @@ pub struct IntoIter { /// ```rust /// use std::sync::mpsc::channel; /// use std::thread; +/// /// let (sender, receiver) = channel(); /// let sender2 = sender.clone(); +/// /// // First thread owns sender /// thread::spawn(move || { /// sender.send(1).unwrap(); /// }); +/// /// // Second thread owns sender2 /// thread::spawn(move || { /// sender2.send(2).unwrap(); /// }); +/// /// let msg = receiver.recv().unwrap(); /// let msg2 = receiver.recv().unwrap(); +/// /// assert_eq!(3, msg + msg2); /// ``` #[stable(feature = "rust1", since = "1.0.0")] @@ -1097,12 +1105,15 @@ impl Receiver { /// ```rust /// use std::sync::mpsc::channel; /// use std::thread; + /// /// let (send, recv) = channel(); + /// /// thread::spawn(move || { /// send.send(1u8).unwrap(); /// send.send(2u8).unwrap(); /// send.send(3u8).unwrap(); /// }); + /// /// for x in recv.iter() { /// println!("Got: {}", x); /// } -- cgit 1.4.1-3-g733a5