1use crate::job::*;
2use crate::registry::Registry;
3use crate::unwind;
4use std::mem;
5use 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/// ```
60pub fn spawn<F>(func: F)
61where
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.
71pub(super) unsafe fn spawn_in<F>(func: F, registry: &Arc<Registry>)
72where
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
86unsafe fn spawn_job<F>(func: F, registry: &Arc<Registry>) -> JobRef
87where
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
130pub fn spawn_fifo<F>(func: F)
131where
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.
141pub(super) unsafe fn spawn_fifo_in<F>(func: F, registry: &Arc<Registry>)
142where
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)]
163mod test;
164