Crate rustc_thread_pool 

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.

Re-exports

pub use worker_local::WorkerLocal;

pub use self::broadcast::BroadcastContext;

pub use self::broadcast::broadcast;

pub use self::broadcast::spawn_broadcast;

pub use self::join::join;

pub use self::join::join_context;

pub(crate) use self::registry::CustomSpawn; 🔒

pub(crate) use self::registry::DefaultSpawn; 🔒

pub(crate) use self::registry::ThreadSpawn; 🔒

pub use self::registry::Registry;

pub use self::registry::ThreadBuilder;

pub use self::registry::mark_blocked_and_wait;

pub use self::registry::mark_unblocked;

pub use self::scope::Scope;

pub use self::scope::ScopeFifo;

pub use self::scope::in_place_scope;

pub use self::scope::in_place_scope_fifo;

pub use self::scope::scope;

pub use self::scope::scope_fifo;

pub use self::spawn::spawn;

pub use self::spawn::spawn_fifo;

pub use self::thread_pool::ThreadPool;

pub use self::thread_pool::Yield;

pub use self::thread_pool::current_thread_has_pending_tasks;

pub use self::thread_pool::current_thread_index;

pub use self::thread_pool::yield_local;

pub use self::thread_pool::yield_now;

pub(crate) use std::any::Any; 🔒

pub(crate) use std::error::Error; 🔒

pub(crate) use std::marker::PhantomData; 🔒

pub(crate) use std::str::FromStr; 🔒

pub(crate) use env; 🔒

pub(crate) use env; 🔒

pub(crate) use fmt; 🔒

pub(crate) use io; 🔒

pub(crate) use thread; 🔒

Modules

broadcast 🔒

compile_fail 🔒

job 🔒

join 🔒

latch 🔒

private 🔒

The public parts of this private module are used to create traits that cannot be implemented outside of our own crate. This way we can feel free to extend those traits without worrying about it being a breaking change for other implementations.

registry 🔒

scope 🔒

Methods for custom fork-join scopes, created by the scope() and in_place_scope() functions. These are a more flexible alternative to join().

sleep 🔒

Code that decides when workers should go to sleep. See README.md for an overview.

spawn 🔒

thread_pool 🔒

Contains support for user-managed thread pools, represented by the the ThreadPool type (see that struct for details).

tlv

Allows access to the Rayon’s thread local value which is preserved when moving jobs across threads

unwind 🔒

Package up unwind recovery. Note that if you are in some sensitive place, you can use the AbortIfPanic helper to protect against accidental panics in the rayon code itself.

worker_local 🔒

Structs

ConfigurationDeprecated

Contains the rayon thread pool configuration. Use ThreadPoolBuilder instead.

FnContext

Provides the calling context to a closure called by join_context.

ThreadPoolBuildError

Error when initializing a thread pool.

ThreadPoolBuilder

Used to create a new ThreadPool or to configure the global rayon thread pool.

Enums

ErrorKind 🔒

Functions

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.

initializeDeprecated

Deprecated in favor of ThreadPoolBuilder::build_global.

max_num_threads

Returns the maximum number of threads that Rayon supports in a single thread-pool.

Type Aliases

AcquireThreadHandler 🔒

The type for a closure that gets invoked before starting computations in a thread. Note that this same closure may be invoked multiple times in parallel.

DeadlockHandler 🔒

The type for a closure that gets invoked when the Rayon thread pool deadlocks

ExitHandler 🔒

The type for a closure that gets invoked when a thread exits. The closure is passed the index of the thread on which it is invoked. Note that this same closure may be invoked multiple times in parallel.

PanicHandler 🔒

The type for a panic handling closure. Note that this same closure may be invoked multiple times in parallel.

ReleaseThreadHandler 🔒

The type for a closure that gets invoked before blocking in a thread. Note that this same closure may be invoked multiple times in parallel.

StartHandler 🔒

The type for a closure that gets invoked when a thread starts. The closure is passed the index of the thread on which it is invoked. Note that this same closure may be invoked multiple times in parallel.