Struct execution_context::ExecutionContext

pub struct ExecutionContext { /* fields omitted */ }

An execution context is a container for the current logical flow of execution.

This container holds all state that needs to be carried forward with the logical thread of execution.

The ExecutionContext class provides the functionality to capture and transfer the encapsulated context across asynchronous points such as threads or tasks.

An execution context can be captured, send and cloned. This permits a context to be carried to other threads.

Methods

impl ExecutionContext

pub fn capture() -> ExecutionContext

Captures the current execution context and returns it.

If the current execution context is suppressed then this will instead capture an empty default scope. Capturing will always succeed.

Capturing the execution context means that the flow of data will branch off here. If a flow local is modified after the flow is captured it will not be reflected in the captured context.

Example

let ec = ExecutionContext::capture();
ec.run(|| {
    // this code runs in the flow of the given execution context.
});

pub fn suppress_flow() -> FlowGuard

Suppresses the flow.

This returns a clonable non-send guard that when dropped restores the flow. This can be used to spawn an operation that should not be considered to be part of the same logical flow. Once a new execution context has been created, that context will start its own flow again.

To permanently disable flow propagation use disable_flow.

Example

{
    let _guard = ExecutionContext::suppress_flow();
    let ec = ExecutionContext::capture();
    ec.run(|| {
        // a new flow is started here because the captured flow was
        // suppressed.
    });
}
// the flow is resumed here

pub fn disable_flow() -> FlowGuard

Permanently disables the flow.

This works similar to suppress_flow but instead of just starting a new flow this permanently disables the flow. The flow can be manually restored by a call to restore_flow.

pub fn restore_flow()

Restores the flow.

In normal situations the flow is restored when the flow guard is dropped. However when for instance the flow is permanently disabled with disable_flow new branches will never have their flow restored. In those situations it might be useful to call into this function to restore the flow.

pub fn is_flow_suppressed() -> bool

Checks if the flow is currently suppressed.

A caller cannot determine if the flow is just temporarily suppressed or permanently disabled.

pub fn run<F: FnOnce() -> R, R>(&self, f: F) -> R

Runs a function in the context of the given execution context.

The captured execution flow will be carried forward. If the flow was suppressed a new flow is started. In case the flow was disabled then it's also disabled here.

Example

let ec = ExecutionContext::capture();
thread::spawn(move || {
    ec.run(|| {
        // the captured execution context is carried into
        // another thread.
    });
});

Trait Implementations

impl Clone for ExecutionContext

fn clone(&self) -> ExecutionContext

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ExecutionContext

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.