Skip to content

Commit

Permalink
Rollup merge of rust-lang#40010 - GuillaumeGomez:barrier-docs, r=frew…
Browse files Browse the repository at this point in the history
…sxcv

Add missing urls and examples into Barrier structs

r? @frewsxcv
  • Loading branch information
frewsxcv authored Feb 23, 2017
2 parents b4cae7a + 58a9dd3 commit b1b5bcd
Showing 1 changed file with 69 additions and 7 deletions.
76 changes: 69 additions & 7 deletions src/libstd/sync/barrier.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ use sync::{Mutex, Condvar};
/// A barrier enables multiple threads to synchronize the beginning
/// of some computation.
///
/// # Examples
///
/// ```
/// use std::sync::{Arc, Barrier};
/// use std::thread;
Expand Down Expand Up @@ -50,8 +52,19 @@ 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
///
/// # Examples
///
/// ```
/// use std::sync::Barrier;
///
/// let barrier = Barrier::new(1);
/// let barrier_wait_result = barrier.wait();
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub struct BarrierWaitResult(bool);

Expand All @@ -65,8 +78,18 @@ impl fmt::Debug for Barrier {
impl Barrier {
/// Creates a new barrier that can block a given number of threads.
///
/// A barrier will block `n`-1 threads which call `wait` and then wake up
/// all threads at once when the `n`th thread calls `wait`.
/// A barrier will block `n`-1 threads which call [`wait`] and then wake up
/// all threads at once when the `n`th thread calls [`wait`].
///
/// [`wait`]: #method.wait
///
/// # Examples
///
/// ```
/// use std::sync::Barrier;
///
/// let barrier = Barrier::new(10);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn new(n: usize) -> Barrier {
Barrier {
Expand All @@ -84,10 +107,37 @@ impl Barrier {
/// Barriers are re-usable after all threads have rendezvoused once, and can
/// be used continuously.
///
/// A single (arbitrary) thread will receive a `BarrierWaitResult` that
/// returns `true` from `is_leader` when returning from this function, and
/// A single (arbitrary) thread will receive a [`BarrierWaitResult`] that
/// returns `true` from [`is_leader`] when returning from this function, and
/// all other threads will receive a result that will return `false` from
/// `is_leader`
/// [`is_leader`].
///
/// [`BarrierWaitResult`]: struct.BarrierWaitResult.html
/// [`is_leader`]: struct.BarrierWaitResult.html#method.is_leader
///
/// # Examples
///
/// ```
/// use std::sync::{Arc, Barrier};
/// use std::thread;
///
/// let mut handles = Vec::with_capacity(10);
/// let barrier = Arc::new(Barrier::new(10));
/// for _ in 0..10 {
/// let c = barrier.clone();
/// // The same messages will be printed together.
/// // You will NOT see any interleaving.
/// handles.push(thread::spawn(move|| {
/// println!("before wait");
/// c.wait();
/// println!("after wait");
/// }));
/// }
/// // Wait for other threads to finish.
/// for handle in handles {
/// handle.join().unwrap();
/// }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn wait(&self) -> BarrierWaitResult {
let mut lock = self.lock.lock().unwrap();
Expand Down Expand Up @@ -120,10 +170,22 @@ impl fmt::Debug for BarrierWaitResult {
}

impl BarrierWaitResult {
/// Returns whether this thread from `wait` is the "leader thread".
/// Returns whether 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.
///
/// [`wait`]: struct.Barrier.html#method.wait
///
/// # Examples
///
/// ```
/// use std::sync::Barrier;
///
/// let barrier = Barrier::new(1);
/// let barrier_wait_result = barrier.wait();
/// println!("{:?}", barrier_wait_result.is_leader());
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_leader(&self) -> bool { self.0 }
}
Expand Down

0 comments on commit b1b5bcd

Please sign in to comment.