Crate `rayon_core`

Rayon-core houses the core stable APIs of Rayon.

These APIs have been mirrored in the Rayon crate and it is recommended to use these from there.

join is used to take two closures and potentially run them in parallel.

It will run in parallel if task B gets stolen before task A can finish.
It will run sequentially if task A finishes before task B is stolen and can continue on task B.

scope creates a scope in which you can run any number of parallel tasks. These tasks can spawn nested tasks and scopes, but given the nature of work stealing, the order of execution can not be guaranteed. The scope will exist until all tasks spawned within the scope have been completed.

spawn add a task into the 'static' or 'global' scope, or a local scope created by the scope() function.

ThreadPool can be used to create your own thread pools (using ThreadPoolBuilder) or to customize the global one. Tasks spawned within the pool (using install(), join(), etc.) will be added to a deque, where it becomes available for work stealing from other threads in the local threadpool.

Global fallback when threading is unsupported

Rayon uses std APIs for threading, but some targets have incomplete implementations that always return Unsupported errors. The WebAssembly wasm32-unknown-unknown and wasm32-wasi targets are notable examples of this. Rather than panicking on the unsupported error when creating the implicit global threadpool, Rayon configures a fallback mode instead.

This fallback mode mostly functions as if it were using a single-threaded "pool", like setting RAYON_NUM_THREADS=1. For example, join will execute its two closures sequentially, since there is no other thread to share the work. However, since the pool is not running independent of the main thread, non-blocking calls like spawn may not execute at all, unless a lower- priority call like broadcast gives them an opening. The fallback mode does not try to emulate anything like thread preemption or async task switching, but yield_now or yield_local can also volunteer execution time.

Explicit ThreadPoolBuilder methods always report their error without any fallback.

Restricting multiple versions

In order to ensure proper coordination between threadpools, and especially to make sure there's only one global threadpool, rayon-core is actively restricted from building multiple versions of itself into a single target. You may see a build error like this in violation:

error: native library `rayon-core` is being linked to by more
than one package, and can only be linked to by one package

While we strive to keep rayon-core semver-compatible, it's still possible to arrive at this situation if different crates have overly restrictive tilde or inequality requirements for rayon-core. The conflicting requirements will need to be resolved before the build will succeed.

Structs

BroadcastContext Provides context to a closure called by broadcast.
Configuration Contains the rayon thread pool configuration. Use ThreadPoolBuilder instead.
FnContext Provides the calling context to a closure called by join_context.
Scope Represents a fork-join scope which can be used to spawn any number of tasks. See [scope()] for more information.
ScopeFifo Represents a fork-join scope which can be used to spawn any number of tasks. Those spawned from the same thread are prioritized in relative FIFO order. See [scope_fifo()] for more information.
ThreadBuilder Thread builder used for customization via ThreadPoolBuilder::spawn_handler.
ThreadPool Represents a user created [thread-pool].
ThreadPoolBuildError Error when initializing a thread pool.
ThreadPoolBuilder Used to create a new ThreadPool or to configure the global rayon thread pool.

Creating a ThreadPool

The following creates a thread pool with 22 threads.

Enums

Yield Result of [yield_now()] or [yield_local()].

Functions

broadcast Executes op within every thread in the current threadpool. If this is called from a non-Rayon thread, it will execute in the global threadpool. Any attempts to use join, scope, or parallel iterators will then operate within that threadpool. When the call has completed on each thread, returns a vector containing all of their return values.
current_num_threads Returns the number of threads in the current registry. If this code is executing within a Rayon thread-pool, then this will be the number of threads for the thread-pool of the current thread. Otherwise, it will be the number of threads for the global thread-pool.
current_thread_has_pending_tasks If called from a Rayon worker thread, indicates whether that thread's local deque still has pending tasks. Otherwise, returns None. For more information, see [the ThreadPool::current_thread_has_pending_tasks() method][m].
current_thread_index If called from a Rayon worker thread, returns the index of that thread within its current pool; if not called from a Rayon thread, returns None.
in_place_scope Creates a "fork-join" scope s and invokes the closure with a reference to s. This closure can then spawn asynchronous tasks into s. Those tasks may run asynchronously with respect to the closure; they may themselves spawn additional tasks into s. When the closure returns, it will block until all tasks that have been spawned into s complete.
in_place_scope_fifo Creates a "fork-join" scope s with FIFO order, and invokes the closure with a reference to s. This closure can then spawn asynchronous tasks into s. Those tasks may run asynchronously with respect to the closure; they may themselves spawn additional tasks into s. When the closure returns, it will block until all tasks that have been spawned into s complete.
initialize Deprecated in favor of ThreadPoolBuilder::build_global.
join Takes two closures and potentially runs them in parallel. It returns a pair of the results from those closures.
join_context Identical to join, except that the closures have a parameter that provides context for the way the closure has been called, especially indicating whether they're executing on a different thread than where join_context was called. This will occur if the second job is stolen by a different thread, or if join_context was called from outside the thread pool to begin with.
max_num_threads Returns the maximum number of threads that Rayon supports in a single thread-pool.
scope Creates a "fork-join" scope s and invokes the closure with a reference to s. This closure can then spawn asynchronous tasks into s. Those tasks may run asynchronously with respect to the closure; they may themselves spawn additional tasks into s. When the closure returns, it will block until all tasks that have been spawned into s complete.
scope_fifo Creates a "fork-join" scope s with FIFO order, and invokes the closure with a reference to s. This closure can then spawn asynchronous tasks into s. Those tasks may run asynchronously with respect to the closure; they may themselves spawn additional tasks into s. When the closure returns, it will block until all tasks that have been spawned into s complete.
spawn 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][scope] to create a scope.
spawn_broadcast Spawns an asynchronous task on every thread in this thread-pool. This task will run in the implicit, global scope, which means that it may outlast the current stack frame -- therefore, it cannot capture any references onto the stack (you will likely need a move closure).
spawn_fifo Fires off a task into the Rayon threadpool 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_fifo() function to create a scope.
yield_local Cooperatively yields execution to local Rayon work.
yield_now Cooperatively yields execution to Rayon.

Global fallback when threading is unsupported

Restricting multiple versions

Structs

Creating a ThreadPool

Enums

Functions