Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

Rollup of 7 pull requests #41513

Closed
wants to merge 23 commits into from
Closed
Changes from 1 commit
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
a42c025
Add bootstrap support for android
malbarbo Apr 18, 2017
87d3272
Pass `--format-version 1` to `cargo metadata`.
kennytm Apr 17, 2017
f2bbd45
Support AddressSanitizer and ThreadSanitizer on x86_64-apple-darwin.
kennytm Apr 17, 2017
b455737
Force link with an absolute rpath when using sanitizer on macOS.
kennytm Apr 20, 2017
d7efbec
Adding links and examples for various mspc pages #29377
projektir Apr 21, 2017
2111aff
Add Vec::splice and String::splice
SimonSapin Apr 8, 2017
b85e2e4
Update splice impl
mattico Apr 8, 2017
cec00ba
Improve splice docs and tests
mattico Apr 8, 2017
c3baa8c
Use Vec::splice impl in string::Splice::drop()
mattico Apr 8, 2017
7b86ba0
Add splice to the unstable book.
mattico Apr 8, 2017
f852e3f
use the word 'length' in Vec::len's docs
steveklabnik Apr 24, 2017
612bb1f
rustc: rename some of the queries to match tcx methods.
eddyb Apr 24, 2017
9bde6b6
rustc: expose the common DUMMY_SP query case as tcx methods.
eddyb Apr 24, 2017
feae5a0
Add Splice forget test
mattico Apr 24, 2017
decf759
rustc: use tcx.at(span) to set the location of a query.
eddyb Apr 24, 2017
009f45f
Run tests for the cargo submodule in tree
alexcrichton Apr 18, 2017
0547f71
Rollup merge of #40434 - mattico:splice-update, r=alexcrichton
frewsxcv Apr 24, 2017
80a45da
Rollup merge of #41352 - kennytm:macos-sanitizers, r=alexcrichton
frewsxcv Apr 24, 2017
2f36312
Rollup merge of #41362 - alexcrichton:run-cargot-ests, r=aturon
frewsxcv Apr 24, 2017
9fb3885
Rollup merge of #41370 - malbarbo:android-bootstrap, r=alexcrichton
frewsxcv Apr 24, 2017
f8de13c
Rollup merge of #41438 - projektir:mpsc_docs, r=alexcrichton
frewsxcv Apr 24, 2017
7de8da5
Rollup merge of #41500 - steveklabnik:gh37866, r=frewsxcv
frewsxcv Apr 24, 2017
4d6b278
Rollup merge of #41504 - eddyb:query-api, r=nikomatsakis
frewsxcv Apr 24, 2017
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Adding links and examples for various mspc pages #29377
projektir committed Apr 22, 2017
commit d7efbec962b574cdea760be62ea8bb0fcae9d702
283 changes: 254 additions & 29 deletions src/libstd/sync/mpsc/mod.rs
Original file line number Diff line number Diff line change
@@ -297,12 +297,14 @@ mod sync;
mod mpsc_queue;
mod spsc_queue;

/// The receiving-half of Rust's channel type. This half can only be owned by
/// one thread.
/// The receiving half of Rust's [`channel`] (or [`sync_channel`]) type.
/// This half can only be owned by one thread.
///
/// Messages sent to the channel can be retrieved using [`recv`].
///
/// [`recv`]: ../../../std/sync/mpsc/struct.Receiver.html#method.recv
/// [`channel`]: fn.channel.html
/// [`sync_channel`]: fn.sync_channel.html
/// [`recv`]: struct.Receiver.html#method.recv
///
/// # Examples
///
@@ -336,51 +338,128 @@ unsafe impl<T: Send> Send for Receiver<T> { }
#[stable(feature = "rust1", since = "1.0.0")]
impl<T> !Sync for Receiver<T> { }

/// 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
/// An iterator over messages on a [`Receiver`], created by [`iter`].
///
/// 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.
///
/// [`iter`]: struct.Receiver.html#method.iter
/// [`Receiver`]: struct.Receiver.html
/// [`next`]: ../../../std/iter/trait.Iterator.html#tymethod.next
/// [`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).unwrap();
/// send.send(2u8).unwrap();
/// send.send(3u8).unwrap();
/// });
///
/// for x in recv.iter() {
/// println!("Got: {}", x);
/// }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Iter<'a, T: 'a> {
rx: &'a Receiver<T>
}

/// 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.
/// An iterator that attempts to yield all pending values for a [`Receiver`],
/// created by [`try_iter`].
///
/// [`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
/// This iterator will never block the caller in order to wait for data to
/// become available. Instead, it will return [`None`].
///
/// [`Receiver`]: struct.Receiver.html
/// [`try_iter`]: struct.Receiver.html#method.try_iter
/// [`None`]: ../../../std/option/enum.Option.html#variant.None
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
/// use std::time::Duration;
///
/// let (sender, receiver) = channel();
///
/// // Nothing is in the buffer yet
/// assert!(receiver.try_iter().next().is_none());
/// println!("Nothing in the buffer...");
///
/// thread::spawn(move || {
/// sender.send(1).unwrap();
/// sender.send(2).unwrap();
/// sender.send(3).unwrap();
/// });
///
/// println!("Going to sleep...");
/// thread::sleep(Duration::from_secs(2)); // block for two seconds
///
/// for x in receiver.try_iter() {
/// println!("Got: {}", x);
/// }
/// ```
#[stable(feature = "receiver_try_iter", since = "1.15.0")]
#[derive(Debug)]
pub struct TryIter<'a, T: 'a> {
rx: &'a Receiver<T>
}

/// 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
/// returned when the corresponding channel has hung up.
/// An owning iterator over messages on a [`Receiver`],
/// created by **Receiver::into_iter**.
///
/// This iterator will block whenever [`next`]
/// is called, waiting for a new message, and [`None`] will be
/// returned if the corresponding channel has hung up.
///
/// [`Receiver`]: struct.Receiver.html
/// [`next`]: ../../../std/iter/trait.Iterator.html#tymethod.next
/// [`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).unwrap();
/// send.send(2u8).unwrap();
/// send.send(3u8).unwrap();
/// });
///
/// for x in recv.into_iter() {
/// println!("Got: {}", x);
/// }
/// ```
#[stable(feature = "receiver_into_iter", since = "1.1.0")]
#[derive(Debug)]
pub struct IntoIter<T> {
rx: Receiver<T>
}

/// The sending-half of Rust's asynchronous channel type. This half can only be
/// 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
/// [`channel`]: fn.channel.html
/// [`send`]: struct.Sender.html#method.send
///
/// # Examples
///
@@ -419,12 +498,55 @@ unsafe impl<T: Send> Send for Sender<T> { }
#[stable(feature = "rust1", since = "1.0.0")]
impl<T> !Sync for Sender<T> { }

/// 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.
/// The sending-half of Rust's synchronous [`sync_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`] or [`try_send`].
///
/// [`send`] will block if there is no space in the internal buffer.
///
/// [`sync_channel`]: fn.sync_channel.html
/// [`send`]: struct.SyncSender.html#method.send
/// [`try_send`]: struct.SyncSender.html#method.try_send
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::sync_channel;
/// use std::thread;
///
/// [`send`]: ../../../std/sync/mpsc/struct.Sender.html#method.send
/// [`SyncSender::send`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.send
/// // Create a sync_channel with buffer size 2
/// let (sync_sender, receiver) = sync_channel(2);
/// let sync_sender2 = sync_sender.clone();
///
/// // First thread owns sync_sender
/// thread::spawn(move || {
/// sync_sender.send(1).unwrap();
/// sync_sender.send(2).unwrap();
/// });
///
/// // Second thread owns sync_sender2
/// thread::spawn(move || {
/// sync_sender2.send(3).unwrap();
/// // thread will now block since the buffer is full
/// println!("Thread unblocked!");
/// });
///
/// let mut msg;
///
/// msg = receiver.recv().unwrap();
/// println!("message {} received", msg);
///
/// // "Thread unblocked!" will be printed now
///
/// msg = receiver.recv().unwrap();
/// println!("message {} received", msg);
///
/// msg = receiver.recv().unwrap();
///
/// println!("message {} received", msg);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct SyncSender<T> {
inner: Arc<sync::Packet<T>>,
@@ -823,15 +945,37 @@ impl<T> SyncSender<T> {
/// Note that a successful send does *not* guarantee that the receiver will
/// ever see the data if there is a buffer on this channel. Items may be
/// enqueued in the internal buffer for the receiver to receive at a later
/// 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.
/// time. If the buffer size is 0, however, the channel becomes a rendezvous
/// channel and it guarantees 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
/// information.
///
/// [`Err`]: ../../../std/result/enum.Result.html#variant.Err
/// [`Receiver`]: ../../../std/sync/mpsc/struct.Receiver.html
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::sync_channel;
/// use std::thread;
///
/// // Create a rendezvous sync_channel with buffer size 0
/// let (sync_sender, receiver) = sync_channel(0);
///
/// thread::spawn(move || {
/// println!("sending message...");
/// sync_sender.send(1).unwrap();
/// // Thread is now blocked until the message is received
///
/// println!("...message received!");
/// });
///
/// let msg = receiver.recv().unwrap();
/// assert_eq!(1, msg);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn send(&self, t: T) -> Result<(), SendError<T>> {
self.inner.send(t).map_err(SendError)
@@ -844,11 +988,48 @@ impl<T> SyncSender<T> {
/// 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 [`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
/// [`send`]: ../../../std/sync/mpsc/struct.SyncSender.html#method.send
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::sync_channel;
/// use std::thread;
///
/// // Create a sync_channel with buffer size 1
/// let (sync_sender, receiver) = sync_channel(1);
/// let sync_sender2 = sync_sender.clone();
///
/// // First thread owns sync_sender
/// thread::spawn(move || {
/// sync_sender.send(1).unwrap();
/// sync_sender.send(2).unwrap();
/// // Thread blocked
/// });
///
/// // Second thread owns sync_sender2
/// thread::spawn(move || {
/// // This will return an error and send
/// // no message if the buffer is full
/// sync_sender2.try_send(3).is_err();
/// });
///
/// let mut msg;
/// msg = receiver.recv().unwrap();
/// println!("message {} received", msg);
///
/// msg = receiver.recv().unwrap();
/// println!("message {} received", msg);
///
/// // Third message may have never been sent
/// match receiver.try_recv() {
/// Ok(msg) => println!("message {} received", msg),
/// Err(_) => println!("the third message was never sent"),
/// }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn try_send(&self, t: T) -> Result<(), TrySendError<T>> {
self.inner.try_send(t)
@@ -894,6 +1075,21 @@ impl<T> Receiver<T> {
///
/// This is useful for a flavor of "optimistic check" before deciding to
/// block on a receiver.
///
/// Compared with [`recv`], this function has two failure cases instead of one
/// (one for disconnection, one for an empty buffer).
///
/// [`recv`]: struct.Receiver.html#method.recv
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::{Receiver, channel};
///
/// let (_, receiver): (_, Receiver<i32>) = channel();
///
/// assert!(receiver.try_recv().is_err());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn try_recv(&self) -> Result<T, TryRecvError> {
loop {
@@ -949,16 +1145,17 @@ impl<T> Receiver<T> {
///
/// 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
/// return that message.
/// sent to the corresponding [`Sender`] (or [`SyncSender`]), 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
/// 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
/// [`Sender`]: struct.Sender.html
/// [`SyncSender`]: struct.SyncSender.html
/// [`Err`]: ../../../std/result/enum.Result.html#variant.Err
///
/// # Examples
@@ -1040,16 +1237,17 @@ impl<T> Receiver<T> {
///
/// 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
/// return that message.
/// sent to the corresponding [`Sender`] (or [`SyncSender`]), 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
/// 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
/// [`Sender`]: struct.Sender.html
/// [`SyncSender`]: struct.SyncSender.html
/// [`Err`]: ../../../std/result/enum.Result.html#variant.Err
///
/// # Examples
@@ -1163,6 +1361,33 @@ impl<T> Receiver<T> {
/// user by waiting for values.
///
/// [`panic!`]: ../../../std/macro.panic.html
///
/// # Examples
///
/// ```rust
/// use std::sync::mpsc::channel;
/// use std::thread;
/// use std::time::Duration;
///
/// let (sender, receiver) = channel();
///
/// // Nothing is in the buffer yet
/// assert!(receiver.try_iter().next().is_none());
/// println!("Nothing in the buffer...");
///
/// thread::spawn(move || {
/// sender.send(1).unwrap();
/// sender.send(2).unwrap();
/// sender.send(3).unwrap();
/// });
///
/// println!("Going to sleep...");
/// thread::sleep(Duration::from_secs(2)); // block for two seconds
///
/// for x in receiver.try_iter() {
/// println!("Got: {}", x);
/// }
/// ```
#[stable(feature = "receiver_try_iter", since = "1.15.0")]
pub fn try_iter(&self) -> TryIter<T> {
TryIter { rx: self }