Struct rayon::Configuration

pub struct Configuration { /* fields omitted */ }

Contains the rayon thread pool configuration.

Methods

impl Configuration

pub fn new() -> Configuration

Creates and return a valid rayon thread pool configuration, but does not initialize it.

pub fn build(self) -> Result<ThreadPool, Box<dyn Error + 'static>>

Create a new ThreadPool initialized using this configuration.

pub fn thread_name<F>(self, closure: F) -> Configuration where
    F: FnMut(usize) -> String + 'static, 

Set a closure which takes a thread index and returns the thread's name.

pub fn num_threads(self, num_threads: usize) -> Configuration

Set the number of threads to be used in the rayon threadpool.

If you specify a non-zero number of threads using this function, then the resulting thread-pools are guaranteed to start at most this number of threads.

If num_threads is 0, or you do not call this function, then the Rayon runtime will select the number of threads automatically. At present, this is based on the RAYON_NUM_THREADS environment variable (if set), or the number of logical CPUs (otherwise). In the future, however, the default behavior may change to dynamically add or remove threads as needed.

Future compatibility warning: Given the default behavior may change in the future, if you wish to rely on a fixed number of threads, you should use this function to specify that number. To reproduce the current default behavior, you may wish to use the num_cpus crate to query the number of CPUs dynamically.

Old environment variable: RAYON_NUM_THREADS is a one-to-one replacement of the now deprecated RAYON_RS_NUM_CPUS environment variable. If both variables are specified, RAYON_NUM_THREADS will be prefered.

pub fn panic_handler<H>(self, panic_handler: H) -> Configuration where
    H: Fn(Box<dyn Any + 'static + Send>) + Send + Sync + 'static, 

Normally, whenever Rayon catches a panic, it tries to propagate it to someplace sensible, to try and reflect the semantics of sequential execution. But in some cases, particularly with the spawn() APIs, there is no obvious place where we should propagate the panic to. In that case, this panic handler is invoked.

If no panic handler is set, the default is to abort the process, under the principle that panics should not go unobserved.

If the panic handler itself panics, this will abort the process. To prevent this, wrap the body of your panic handler in a call to std::panic::catch_unwind().

pub fn stack_size(self, stack_size: usize) -> Configuration

Set the stack size of the worker threads

pub fn breadth_first(self) -> Configuration

Suggest to worker threads that they execute spawned jobs in a "breadth-first" fashion. Typically, when a worker thread is idle or blocked, it will attempt to execute the job from the top of its local deque of work (i.e., the job most recently spawned). If this flag is set to true, however, workers will prefer to execute in a breadth-first fashion -- that is, they will search for jobs at the bottom of their local deque. (At present, workers always steal from the bottom of other worker's deques, regardless of the setting of this flag.)

If you think of the tasks as a tree, where a parent task spawns its children in the tree, then this flag loosely corresponds to doing a breadth-first traversal of the tree, whereas the default would be to do a depth-first traversal.

Note that this is an "execution hint". Rayon's task execution is highly dynamic and the precise order in which independent tasks are executed is not intended to be guaranteed.

pub fn start_handler<H>(self, start_handler: H) -> Configuration where
    H: Fn(usize) + Send + Sync + 'static, 

Set a callback to be invoked on thread start.

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. If this closure panics, the panic will be passed to the panic handler. If that handler returns, then startup will continue normally.

pub fn exit_handler<H>(self, exit_handler: H) -> Configuration where
    H: Fn(usize) + Send + Sync + 'static, 

Set a callback to be invoked on thread exit.

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. If this closure panics, the panic will be passed to the panic handler. If that handler returns, then the thread will exit normally.

Trait Implementations

impl Default for Configuration

fn default() -> Configuration

Returns the "default value" for a type.

impl Debug for Configuration

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.