vendor/rayon-core/src/spawn/mod.rs

   1 use crate::job::*;
   2 use crate::registry::Registry;
   3 use crate::unwind;
   4 use std::mem;
   5 use std::sync::Arc;
   6
   7 /// Fires off a task into the Rayon threadpool in the "static" or
   8 /// "global" scope.  Just like a standard thread, this task is not
   9 /// tied to the current stack frame, and hence it cannot hold any
  10 /// references other than those with `'static` lifetime. If you want
  11 /// to spawn a task that references stack data, use [the `scope()`
  12 /// function][scope] to create a scope.
  13 ///
  14 /// [scope]: fn.scope.html
  15 ///
  16 /// Since tasks spawned with this function cannot hold references into
  17 /// the enclosing stack frame, you almost certainly want to use a
  18 /// `move` closure as their argument (otherwise, the closure will
  19 /// typically hold references to any variables from the enclosing
  20 /// function that you happen to use).
  21 ///
  22 /// This API assumes that the closure is executed purely for its
  23 /// side-effects (i.e., it might send messages, modify data protected
  24 /// by a mutex, or some such thing).
  25 ///
  26 /// There is no guaranteed order of execution for spawns, given that
  27 /// other threads may steal tasks at any time. However, they are
  28 /// generally prioritized in a LIFO order on the thread from which
  29 /// they were spawned. Other threads always steal from the other end of
  30 /// the deque, like FIFO order.  The idea is that "recent" tasks are
  31 /// most likely to be fresh in the local CPU's cache, while other
  32 /// threads can steal older "stale" tasks.  For an alternate approach,
  33 /// consider [`spawn_fifo()`] instead.
  34 ///
  35 /// [`spawn_fifo()`]: fn.spawn_fifo.html
  36 ///
  37 /// # Panic handling
  38 ///
  39 /// If this closure should panic, the resulting panic will be
  40 /// propagated to the panic handler registered in the `ThreadPoolBuilder`,
  41 /// if any.  See [`ThreadPoolBuilder::panic_handler()`][ph] for more
  42 /// details.
  43 ///
  44 /// [ph]: struct.ThreadPoolBuilder.html#method.panic_handler
  45 ///
  46 /// # Examples
  47 ///
  48 /// This code creates a Rayon task that increments a global counter.
  49 ///
  50 /// ```rust
  51 /// # use rayon_core as rayon;
  52 /// use std::sync::atomic::{AtomicUsize, Ordering, ATOMIC_USIZE_INIT};
  53 ///
  54 /// static GLOBAL_COUNTER: AtomicUsize = ATOMIC_USIZE_INIT;
  55 ///
  56 /// rayon::spawn(move || {
  57 ///     GLOBAL_COUNTER.fetch_add(1, Ordering::SeqCst);
  58 /// });
  59 /// ```
  60 pub fn spawn<F>(func: F)
  61 where
  62     F: FnOnce() + Send + 'static,
  63 {
  64     // We assert that current registry has not terminated.
  65     unsafe { spawn_in(func, &Registry::current()) }
  66 }
  67
  68 /// Spawns an asynchronous job in `registry.`
  69 ///
  70 /// Unsafe because `registry` must not yet have terminated.
  71 pub(super) unsafe fn spawn_in<F>(func: F, registry: &Arc<Registry>)
  72 where
  73     F: FnOnce() + Send + 'static,
  74 {
  75     // We assert that this does not hold any references (we know
  76     // this because of the `'static` bound in the interface);
  77     // moreover, we assert that the code below is not supposed to
  78     // be able to panic, and hence the data won't leak but will be
  79     // enqueued into some deque for later execution.
  80     let abort_guard = unwind::AbortIfPanic; // just in case we are wrong, and code CAN panic
  81     let job_ref = spawn_job(func, registry);
  82     registry.inject_or_push(job_ref);
  83     mem::forget(abort_guard);
  84 }
  85
  86 unsafe fn spawn_job<F>(func: F, registry: &Arc<Registry>) -> JobRef
  87 where
  88     F: FnOnce() + Send + 'static,
  89 {
  90     // Ensure that registry cannot terminate until this job has
  91     // executed. This ref is decremented at the (*) below.
  92     registry.increment_terminate_count();
  93
  94     HeapJob::new({
  95         let registry = Arc::clone(registry);
  96         move || {
  97             registry.catch_unwind(func);
  98             registry.terminate(); // (*) permit registry to terminate now
  99         }
 100     })
 101     .into_static_job_ref()
 102 }
 103
 104 /// Fires off a task into the Rayon threadpool in the "static" or
 105 /// "global" scope.  Just like a standard thread, this task is not
 106 /// tied to the current stack frame, and hence it cannot hold any
 107 /// references other than those with `'static` lifetime. If you want
 108 /// to spawn a task that references stack data, use [the `scope_fifo()`
 109 /// function](fn.scope_fifo.html) to create a scope.
 110 ///
 111 /// The behavior is essentially the same as [the `spawn`
 112 /// function](fn.spawn.html), except that calls from the same thread
 113 /// will be prioritized in FIFO order. This is similar to the now-
 114 /// deprecated [`breadth_first`] option, except the effect is isolated
 115 /// to relative `spawn_fifo` calls, not all threadpool tasks.
 116 ///
 117 /// For more details on this design, see Rayon [RFC #1].
 118 ///
 119 /// [`breadth_first`]: struct.ThreadPoolBuilder.html#method.breadth_first
 120 /// [RFC #1]: https://github.com/rayon-rs/rfcs/blob/master/accepted/rfc0001-scope-scheduling.md
 121 ///
 122 /// # Panic handling
 123 ///
 124 /// If this closure should panic, the resulting panic will be
 125 /// propagated to the panic handler registered in the `ThreadPoolBuilder`,
 126 /// if any.  See [`ThreadPoolBuilder::panic_handler()`][ph] for more
 127 /// details.
 128 ///
 129 /// [ph]: struct.ThreadPoolBuilder.html#method.panic_handler
 130 pub fn spawn_fifo<F>(func: F)
 131 where
 132     F: FnOnce() + Send + 'static,
 133 {
 134     // We assert that current registry has not terminated.
 135     unsafe { spawn_fifo_in(func, &Registry::current()) }
 136 }
 137
 138 /// Spawns an asynchronous FIFO job in `registry.`
 139 ///
 140 /// Unsafe because `registry` must not yet have terminated.
 141 pub(super) unsafe fn spawn_fifo_in<F>(func: F, registry: &Arc<Registry>)
 142 where
 143     F: FnOnce() + Send + 'static,
 144 {
 145     // We assert that this does not hold any references (we know
 146     // this because of the `'static` bound in the interface);
 147     // moreover, we assert that the code below is not supposed to
 148     // be able to panic, and hence the data won't leak but will be
 149     // enqueued into some deque for later execution.
 150     let abort_guard = unwind::AbortIfPanic; // just in case we are wrong, and code CAN panic
 151     let job_ref = spawn_job(func, registry);
 152
 153     // If we're in the pool, use our thread's private fifo for this thread to execute
 154     // in a locally-FIFO order.  Otherwise, just use the pool's global injector.
 155     match registry.current_thread() {
 156         Some(worker) => worker.push_fifo(job_ref),
 157         None => registry.inject(&[job_ref]),
 158     }
 159     mem::forget(abort_guard);
 160 }
 161
 162 #[cfg(test)]
 163 mod test;