Function rayon_core::spawn

source ·
pub fn spawn<F>(func: F)
where F: FnOnce() + Send + 'static,
Expand description

Puts the task into the Rayon threadpool’s job queue in the “static” or “global” scope. Just like a standard thread, this task is not tied to the current stack frame, and hence it cannot hold any references other than those with 'static lifetime. If you want to spawn a task that references stack data, use the scope() function to create a scope.

Since tasks spawned with this function cannot hold references into the enclosing stack frame, you almost certainly want to use a move closure as their argument (otherwise, the closure will typically hold references to any variables from the enclosing function that you happen to use).

This API assumes that the closure is executed purely for its side-effects (i.e., it might send messages, modify data protected by a mutex, or some such thing).

There is no guaranteed order of execution for spawns, given that other threads may steal tasks at any time. However, they are generally prioritized in a LIFO order on the thread from which they were spawned. Other threads always steal from the other end of the deque, like FIFO order. The idea is that “recent” tasks are most likely to be fresh in the local CPU’s cache, while other threads can steal older “stale” tasks. For an alternate approach, consider spawn_fifo() instead.

§Panic handling

If this closure should panic, the resulting panic will be propagated to the panic handler registered in the ThreadPoolBuilder, if any. See ThreadPoolBuilder::panic_handler() for more details.

§Examples

This code creates a Rayon task that increments a global counter.

use std::sync::atomic::{AtomicUsize, Ordering, ATOMIC_USIZE_INIT};

static GLOBAL_COUNTER: AtomicUsize = ATOMIC_USIZE_INIT;

rayon::spawn(move || {
    GLOBAL_COUNTER.fetch_add(1, Ordering::SeqCst);
});