library/std/src/sync/barrier.rs

   1 #[cfg(test)]
   2 mod tests;
   3
   4 use crate::fmt;
   5 use crate::sync::{Condvar, Mutex};
   6
   7 /// A barrier enables multiple threads to synchronize the beginning
   8 /// of some computation.
   9 ///
  10 /// # Examples
  11 ///
  12 /// ```
  13 /// use std::sync::{Arc, Barrier};
  14 /// use std::thread;
  15 ///
  16 /// let mut handles = Vec::with_capacity(10);
  17 /// let barrier = Arc::new(Barrier::new(10));
  18 /// for _ in 0..10 {
  19 ///     let c = barrier.clone();
  20 ///     // The same messages will be printed together.
  21 ///     // You will NOT see any interleaving.
  22 ///     handles.push(thread::spawn(move|| {
  23 ///         println!("before wait");
  24 ///         c.wait();
  25 ///         println!("after wait");
  26 ///     }));
  27 /// }
  28 /// // Wait for other threads to finish.
  29 /// for handle in handles {
  30 ///     handle.join().unwrap();
  31 /// }
  32 /// ```
  33 #[stable(feature = "rust1", since = "1.0.0")]
  34 pub struct Barrier {
  35     lock: Mutex<BarrierState>,
  36     cvar: Condvar,
  37     num_threads: usize,
  38 }
  39
  40 // The inner state of a double barrier
  41 struct BarrierState {
  42     count: usize,
  43     generation_id: usize,
  44 }
  45
  46 /// A `BarrierWaitResult` is returned by [`wait`] when all threads in the [`Barrier`]
  47 /// have rendezvoused.
  48 ///
  49 /// [`wait`]: struct.Barrier.html#method.wait
  50 /// [`Barrier`]: struct.Barrier.html
  51 ///
  52 /// # Examples
  53 ///
  54 /// ```
  55 /// use std::sync::Barrier;
  56 ///
  57 /// let barrier = Barrier::new(1);
  58 /// let barrier_wait_result = barrier.wait();
  59 /// ```
  60 #[stable(feature = "rust1", since = "1.0.0")]
  61 pub struct BarrierWaitResult(bool);
  62
  63 #[stable(feature = "std_debug", since = "1.16.0")]
  64 impl fmt::Debug for Barrier {
  65     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  66         f.pad("Barrier { .. }")
  67     }
  68 }
  69
  70 impl Barrier {
  71     /// Creates a new barrier that can block a given number of threads.
  72     ///
  73     /// A barrier will block `n`-1 threads which call [`wait`] and then wake up
  74     /// all threads at once when the `n`th thread calls [`wait`].
  75     ///
  76     /// [`wait`]: #method.wait
  77     ///
  78     /// # Examples
  79     ///
  80     /// ```
  81     /// use std::sync::Barrier;
  82     ///
  83     /// let barrier = Barrier::new(10);
  84     /// ```
  85     #[stable(feature = "rust1", since = "1.0.0")]
  86     pub fn new(n: usize) -> Barrier {
  87         Barrier {
  88             lock: Mutex::new(BarrierState { count: 0, generation_id: 0 }),
  89             cvar: Condvar::new(),
  90             num_threads: n,
  91         }
  92     }
  93
  94     /// Blocks the current thread until all threads have rendezvoused here.
  95     ///
  96     /// Barriers are re-usable after all threads have rendezvoused once, and can
  97     /// be used continuously.
  98     ///
  99     /// A single (arbitrary) thread will receive a [`BarrierWaitResult`] that
 100     /// returns `true` from [`is_leader`] when returning from this function, and
 101     /// all other threads will receive a result that will return `false` from
 102     /// [`is_leader`].
 103     ///
 104     /// [`BarrierWaitResult`]: struct.BarrierWaitResult.html
 105     /// [`is_leader`]: struct.BarrierWaitResult.html#method.is_leader
 106     ///
 107     /// # Examples
 108     ///
 109     /// ```
 110     /// use std::sync::{Arc, Barrier};
 111     /// use std::thread;
 112     ///
 113     /// let mut handles = Vec::with_capacity(10);
 114     /// let barrier = Arc::new(Barrier::new(10));
 115     /// for _ in 0..10 {
 116     ///     let c = barrier.clone();
 117     ///     // The same messages will be printed together.
 118     ///     // You will NOT see any interleaving.
 119     ///     handles.push(thread::spawn(move|| {
 120     ///         println!("before wait");
 121     ///         c.wait();
 122     ///         println!("after wait");
 123     ///     }));
 124     /// }
 125     /// // Wait for other threads to finish.
 126     /// for handle in handles {
 127     ///     handle.join().unwrap();
 128     /// }
 129     /// ```
 130     #[stable(feature = "rust1", since = "1.0.0")]
 131     pub fn wait(&self) -> BarrierWaitResult {
 132         let mut lock = self.lock.lock().unwrap();
 133         let local_gen = lock.generation_id;
 134         lock.count += 1;
 135         if lock.count < self.num_threads {
 136             // We need a while loop to guard against spurious wakeups.
 137             // https://en.wikipedia.org/wiki/Spurious_wakeup
 138             while local_gen == lock.generation_id && lock.count < self.num_threads {
 139                 lock = self.cvar.wait(lock).unwrap();
 140             }
 141             BarrierWaitResult(false)
 142         } else {
 143             lock.count = 0;
 144             lock.generation_id = lock.generation_id.wrapping_add(1);
 145             self.cvar.notify_all();
 146             BarrierWaitResult(true)
 147         }
 148     }
 149 }
 150
 151 #[stable(feature = "std_debug", since = "1.16.0")]
 152 impl fmt::Debug for BarrierWaitResult {
 153     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 154         f.debug_struct("BarrierWaitResult").field("is_leader", &self.is_leader()).finish()
 155     }
 156 }
 157
 158 impl BarrierWaitResult {
 159     /// Returns `true` if this thread from [`wait`] is the "leader thread".
 160     ///
 161     /// Only one thread will have `true` returned from their result, all other
 162     /// threads will have `false` returned.
 163     ///
 164     /// [`wait`]: struct.Barrier.html#method.wait
 165     ///
 166     /// # Examples
 167     ///
 168     /// ```
 169     /// use std::sync::Barrier;
 170     ///
 171     /// let barrier = Barrier::new(1);
 172     /// let barrier_wait_result = barrier.wait();
 173     /// println!("{:?}", barrier_wait_result.is_leader());
 174     /// ```
 175     #[stable(feature = "rust1", since = "1.0.0")]
 176     pub fn is_leader(&self) -> bool {
 177         self.0
 178     }
 179 }