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
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 |
option |
This module contains the parallel iterator types for options
( |
prelude |
The rayon prelude imports the various |
range |
This module contains the parallel iterator types for ranges
( |
result |
This module contains the parallel iterator types for results
( |
slice |
This module contains the parallel iterator types for slices
( |
str |
This module contains extension methods for |
vec |
This module contains the parallel iterator types for vectors
( |
Structs
Configuration |
Contains the rayon thread pool configuration. |
FnContext |
Provides the calling context to a closure called by |
Scope |
Represents a fork-join scope which can be used to spawn any number of tasks. See |
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 |
join |
The |
join_context |
The |
scope |
Create a "fork-join" scope |
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 |