Crate rayon

source ·
Expand description

Data-parallelism library that makes it easy to convert sequential computations into parallel

Rayon is lightweight and convenient for introducing parallelism into existing code. It guarantees data-race free executions and takes advantage of parallelism when sensible, based on work-load at runtime.

How to use Rayon

There are two ways to use Rayon:

  • High-level parallel constructs are the simplest way to use Rayon and also typically the most efficient.
    • Parallel iterators make it easy to convert a sequential iterator to execute in parallel.
    • The par_sort method sorts &mut [T] slices (or vectors) in parallel.
    • par_extend can be used to efficiently grow collections with items produced by a parallel iterator.
  • Custom tasks let you divide your work into parallel tasks yourself.
    • join is used to subdivide a task into two pieces.
    • scope creates a scope within which you can create any number of parallel tasks.
    • ThreadPoolBuilder can be used to create your own thread pools or customize the global one.

Basic usage and the Rayon prelude

First, you will need to add rayon to your Cargo.toml.

Next, to use parallel iterators or the other high-level methods, you need to import several traits. Those traits are bundled into the module rayon::prelude. It is recommended that you import all of these traits at once by adding use rayon::prelude::* at the top of each module that uses Rayon methods.

These traits give you access to the par_iter method which provides parallel implementations of many iterative functions such as map, for_each, filter, fold, and more.

Crate Layout

Rayon extends many of the types found in the standard library with parallel iterator implementations. The modules in the rayon crate mirror std itself: so, e.g., the option module in Rayon contains parallel iterators for the Option type, which is found in the option module of std. Similarly, the collections module in Rayon offers parallel iterator types for the collections from std. You will rarely need to access these submodules unless you need to name iterator types explicitly.

Targets without threading

Rayon has limited support for targets without std threading implementations. See the rayon_core documentation for more information about its global fallback.

Other questions?

See the Rayon FAQ.

Modules

  • Parallel iterator types for arrays ([T; N])
  • Parallel iterator types for standard collections
  • Traits for writing parallel programs using an iterator-style interface
  • Parallel iterator types for options
  • 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.
  • Parallel iterator types for ranges, the type for values created by a..b expressions
  • Parallel iterator types for inclusive ranges, the type for values created by a..=b expressions
  • Parallel iterator types for results
  • Parallel iterator types for slices
  • Parallel iterator types for strings
  • This module contains the parallel iterator types for owned strings (String). You will rarely need to interact with it directly unless you have need to name one of the iterator types.
  • Parallel iterator types for vectors (Vec<T>)

Structs

Enums

Functions

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • Takes two closures and potentially runs them in parallel. It returns a pair of the results from those closures.
  • 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.
  • Returns the maximum number of threads that Rayon supports in a single thread-pool.
  • 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.
  • 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.
  • 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.
  • 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).
  • 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.
  • Cooperatively yields execution to local Rayon work.
  • Cooperatively yields execution to Rayon.