Expand description
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.
scope() is a more flexible building block compared to join(),
since a loop can be used to spawn any number of tasks without
recursing. However, that flexibility comes at a performance price:
tasks spawned using scope() must be allocated onto the heap,
whereas join() can make exclusive use of the stack. Prefer
join() (or, even better, parallel iterators) where possible.
Example
The Rayon join() function launches two closures and waits for them
to stop. One could implement join() using a scope like so, although
it would be less efficient than the real implementation:
pub fn join<A,B,RA,RB>(oper_a: A, oper_b: B) -> (RA, RB)
where A: FnOnce() -> RA + Send,
B: FnOnce() -> RB + Send,
RA: Send,
RB: Send,
{
let mut result_a: Option<RA> = None;
let mut result_b: Option<RB> = None;
rayon::scope(|s| {
s.spawn(|_| result_a = Some(oper_a()));
s.spawn(|_| result_b = Some(oper_b()));
});
(result_a.unwrap(), result_b.unwrap())
}A note on threading
The closure given to scope() executes in the Rayon thread-pool,
as do those given to spawn(). This means that you can’t access
thread-local variables (well, you can, but they may have
unexpected values).
Task execution
Task execution potentially starts as soon as spawn() is called.
The task will end sometime before scope() returns. Note that the
closure given to scope may return much earlier. In general
the lifetime of a scope created like `scope(body) goes something like this:
- Scope begins when
scope(body)is called - Scope body
body()is invoked- Scope tasks may be spawned
- Scope body returns
- Scope tasks execute, possibly spawning more tasks
- Once all tasks are done, scope ends and
scope()returns
To see how and when tasks are joined, consider this example:
// point start
rayon::scope(|s| {
s.spawn(|s| { // task s.1
s.spawn(|s| { // task s.1.1
rayon::scope(|t| {
t.spawn(|_| ()); // task t.1
t.spawn(|_| ()); // task t.2
});
});
});
s.spawn(|s| { // task s.2
});
// point mid
});
// point endThe various tasks that are run will execute roughly like so:
| (start)
|
| (scope `s` created)
+-----------------------------------------------+ (task s.2)
+-------+ (task s.1) |
| | |
| +---+ (task s.1.1) |
| | | |
| | | (scope `t` created) |
| | +----------------+ (task t.2) |
| | +---+ (task t.1) | |
| (mid) | | | | |
: | + <-+------------+ (scope `t` ends) |
: | | |
|<------+---+-----------------------------------+ (scope `s` ends)
|
| (end)The point here is that everything spawned into scope s will
terminate (at latest) at the same point – right before the
original call to rayon::scope returns. This includes new
subtasks created by other subtasks (e.g., task s.1.1). If a new
scope is created (such as t), the things spawned into that scope
will be joined before that scope returns, which in turn occurs
before the creating task (task s.1.1 in this case) finishes.
There is no guaranteed order of execution for spawns in a scope,
given that other threads may steal tasks at any time. However, they
are generally prioritized in a LIFO order on the thread from which
they were spawned. So in this example, absent any stealing, we can
expect s.2 to execute before s.1, and t.2 before t.1. Other
threads always steal from the other end of the deque, like FIFO
order. The idea is that “recent” tasks are most likely to be fresh
in the local CPU’s cache, while other threads can steal older
“stale” tasks. For an alternate approach, consider
scope_fifo() instead.
Accessing stack data
In general, spawned tasks may access stack data in place that outlives the scope itself. Other data must be fully owned by the spawned task.
let ok: Vec<i32> = vec![1, 2, 3];
rayon::scope(|s| {
let bad: Vec<i32> = vec![4, 5, 6];
s.spawn(|_| {
// We can access `ok` because outlives the scope `s`.
println!("ok: {:?}", ok);
// If we just try to use `bad` here, the closure will borrow `bad`
// (because we are just printing it out, and that only requires a
// borrow), which will result in a compilation error. Read on
// for options.
// println!("bad: {:?}", bad);
});
});As the comments example above suggest, to reference bad we must
take ownership of it. One way to do this is to detach the closure
from the surrounding stack frame, using the move keyword. This
will cause it to take ownership of all the variables it touches,
in this case including both ok and bad:
let ok: Vec<i32> = vec![1, 2, 3];
rayon::scope(|s| {
let bad: Vec<i32> = vec![4, 5, 6];
s.spawn(move |_| {
println!("ok: {:?}", ok);
println!("bad: {:?}", bad);
});
// That closure is fine, but now we can't use `ok` anywhere else,
// since it is owend by the previous task:
// s.spawn(|_| println!("ok: {:?}", ok));
});While this works, it could be a problem if we want to use ok elsewhere.
There are two choices. We can keep the closure as a move closure, but
instead of referencing the variable ok, we create a shadowed variable that
is a borrow of ok and capture that:
let ok: Vec<i32> = vec![1, 2, 3];
rayon::scope(|s| {
let bad: Vec<i32> = vec![4, 5, 6];
let ok: &Vec<i32> = &ok; // shadow the original `ok`
s.spawn(move |_| {
println!("ok: {:?}", ok); // captures the shadowed version
println!("bad: {:?}", bad);
});
// Now we too can use the shadowed `ok`, since `&Vec<i32>` references
// can be shared freely. Note that we need a `move` closure here though,
// because otherwise we'd be trying to borrow the shadowed `ok`,
// and that doesn't outlive `scope`.
s.spawn(move |_| println!("ok: {:?}", ok));
});Another option is not to use the move keyword but instead to take ownership
of individual variables:
let ok: Vec<i32> = vec![1, 2, 3];
rayon::scope(|s| {
let bad: Vec<i32> = vec![4, 5, 6];
s.spawn(|_| {
// Transfer ownership of `bad` into a local variable (also named `bad`).
// This will force the closure to take ownership of `bad` from the environment.
let bad = bad;
println!("ok: {:?}", ok); // `ok` is only borrowed.
println!("bad: {:?}", bad); // refers to our local variable, above.
});
s.spawn(|_| println!("ok: {:?}", ok)); // we too can borrow `ok`
});Panics
If a panic occurs, either in the closure given to scope() or in
any of the spawned jobs, that panic will be propagated and the
call to scope() will panic. If multiple panics occurs, it is
non-deterministic which of their panic values will propagate.
Regardless, once a task is spawned using scope.spawn(), it will
execute, even if the spawning task should later panic. scope()
returns once all spawned jobs have completed, and any panics are
propagated at that point.