# [−][src]Crate rayon

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` and put `extern crate rayon` in your main file (`lib.rs`, `main.rs`).

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.

# Other questions?

See the Rayon FAQ.

## Modules

collections | Parallel iterator types for standard collections
iter | Traits for writing parallel programs using an iterator-style interface
option | Parallel iterator types for options
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 | Parallel iterator types for ranges, the type for values created by `a..b` expressions
range_inclusive | Parallel iterator types for inclusive ranges, the type for values created by `a..=b` expressions
result | Parallel iterator types for results
slice | Parallel iterator types for slices
str | Parallel iterator types for strings
vec | Parallel iterator types for vectors (`Vec<T>`)

## Structs

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.
ScopeFifo | Represents a fork-join scope which can be used to spawn any number of tasks. Those spawned from the same thread are prioritized in relative FIFO order. See `scope_fifo()` for more information.
ThreadBuilder | Thread builder used for customization via `ThreadPoolBuilder::spawn_handler`.
ThreadPool | Represents a user created thread-pool.
ThreadPoolBuildError | Error when initializing a thread pool.
ThreadPoolBuilder | Used to create a new `ThreadPool` or to configure the global rayon thread pool.

## 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.
current_thread_index | 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`.
join | Takes two closures and potentially runs them in parallel. It returns a pair of the results from those closures.
join_context | 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.
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.
scope_fifo | Create 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.
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.
spawn_fifo | 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.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)