Function rayon::scope_fifo

source ·
pub fn scope_fifo<'scope, OP, R>(op: OP) -> R
where OP: FnOnce(&ScopeFifo<'scope>) -> R + Send, R: Send,
Expand description

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.

§Task execution

Tasks in a scope_fifo() run similarly to scope(), but there’s a difference in the order of execution. Consider a similar example:

// point start
rayon::scope_fifo(|s| {
    s.spawn_fifo(|s| { // task s.1
        s.spawn_fifo(|s| { // task s.1.1
            rayon::scope_fifo(|t| {
                t.spawn_fifo(|_| ()); // task t.1
                t.spawn_fifo(|_| ()); // task t.2
            });
        });
    });
    s.spawn_fifo(|s| { // task s.2
    });
    // point mid
});
// point end

The various tasks that are run will execute roughly like so:

| (start)
|
| (FIFO scope `s` created)
+--------------------+ (task s.1)
+-------+ (task s.2) |
|       |            +---+ (task s.1.1)
|       |            |   |
|       |            |   | (FIFO scope `t` created)
|       |            |   +----------------+ (task t.1)
|       |            |   +---+ (task t.2) |
| (mid) |            |   |   |            |
:       |            |   + <-+------------+ (scope `t` ends)
:       |            |   |
|<------+------------+---+ (scope `s` ends)
|
| (end)

Under scope_fifo(), the spawns are prioritized in a FIFO order on the thread from which they were spawned, as opposed to scope()’s LIFO. So in this example, we can expect s.1 to execute before s.2, and t.1 before t.2. Other threads also steal tasks in FIFO order, as usual. Overall, this has roughly the same order as the now-deprecated breadth_first option, except the effect is isolated to a particular scope. If spawns are intermingled from any combination of scope() and scope_fifo(), or from different threads, their order is only specified with respect to spawns in the same scope and thread.

For more details on this design, see Rayon RFC #1.

§Panics

If a panic occurs, either in the closure given to scope_fifo() or in any of the spawned jobs, that panic will be propagated and the call to scope_fifo() 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_fifo(), it will execute, even if the spawning task should later panic. scope_fifo() returns once all spawned jobs have completed, and any panics are propagated at that point.