Crate rayon [] [src]

Data-parallelism library that is easy to convert sequential computations into parallel.

Rayon is lightweight and convenient for application to existing code. It guarantees data-race free executions, and takes advantage of parallelism when sensible, based on work-load at runtime. There are two categories of rayon workloads: parallel iterators and multi-branched recursion (join method).

Parallel Iterators

Parallel iterators are formed using par_iter, par_iter_mut, and into_par_iter functions to iterate by shared reference, mutable reference, or by value respectively. These iterators are chained with computations that can take the shape of map or for_each as an example. This solves embarrassingly parallel tasks that are completely independent of one another.

Examples

Here a string is encrypted using ROT13 leveraging parallelism. Once all the threads are complete, they are collected into a string.

extern crate rayon;
use rayon::prelude::*;
let mut chars: Vec<char> = "A man, a plan, a canal - Panama!".chars().collect();
let encrypted: String = chars.into_par_iter().map(|c| {
       match c {
           'A' ... 'M' | 'a' ... 'm' => ((c as u8) + 13) as char,
           'N' ... 'Z' | 'n' ... 'z' => ((c as u8) - 13) as char,
           _ => c
       }
   }).collect();
   assert_eq!(encrypted, "N zna, n cyna, n pnany - Cnanzn!");

Divide and conquer with join

join takes two closures and runs them in parallel if doing so will improve execution time. Parallel Iterators are implemented using join with work-stealing. Given two tasks that safely run in parallel, one task is queued and another starts processing. If idle threads exist, they begin execution on the queued work.

Examples

Be careful when using this code, it's not being tested!
join(|| do_something(), || do_something_else())
fn quick_sort<T:PartialOrd+Send>(v: &mut [T]) {
   if v.len() > 1 {
       let mid = partition(v);
       let (lo, hi) = v.split_at_mut(mid);
       rayon::join(|| quick_sort(lo),
                   || quick_sort(hi));
   }
}

Rayon Types

Rayon traits are bundled into rayon::prelude::*. To get access to parallel implementations on various standard types include use rayon::prelude::*;

These implementations will give you access to par_iter with parallel implementations of iterative functions including map, for_each, filter, fold, and more.

Crate Layout

Rayon is modeled after std. Types are included in provided modules.

Modules

collections

This module contains the parallel iterator types for standard collections. You will rarely need to interact with it directly unless you have need to name one of the iterator types.

iter

The ParallelIterator module makes it easy to write parallel programs using an iterator-style interface. To get access to all the methods you want, the easiest is to write use rayon::prelude::*; at the top of your module, which will import the various traits and methods you need.

option

This module contains the parallel iterator types for options (Option<T>). You will rarely need to interact with it directly unless you have need to name one of the iterator types.

prelude

The rayon prelude imports the various ParallelIterator traits. The intention is that one can include use rayon::prelude::* and have easy access to the various traits and methods you will need.

range

This module contains the parallel iterator types for ranges (Range<T>); this is the type for values created by a a..b expression. You will rarely need to interact with it directly unless you have need to name one of the iterator types.

result

This module contains the parallel iterator types for results (Result<T, E>). You will rarely need to interact with it directly unless you have need to name one of the iterator types.

slice

This module contains the parallel iterator types for slices ([T]). You will rarely need to interact with it directly unless you have need to name one of those types.

str

This module contains extension methods for String that expose parallel iterators, such as par_split_whitespace(). You will rarely need to interact with it directly, since if you add use rayon::prelude::* to your file, that will include the helper traits defined in this module.

vec

This module contains the parallel iterator types for vectors (Vec<T>). You will rarely need to interact with it directly unless you have need to name one of those types.

Structs

Configuration

Contains the rayon thread pool configuration.

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.

ThreadPool

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.

initialize

Initializes the global thread pool. This initialization is optional. If you do not call this function, the thread pool will be automatically initialized with the default configuration. In fact, calling initialize is not recommended, except for in two scenarios:

join

The join function takes two closures and potentially runs them in parallel. It returns a pair of the results from those closures.

join_context

The join_context function is identical to join, except 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.

scope

Create 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.

spawn

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() function to create a scope.