Struct RefContext

pub struct RefContext(/* private fields */);

A way to share mutable access to a context. This is useful for context chaining. RefContext contains an identical API to Context.

Chaining a context means that the context will be cancelled if a parent context is cancelled. A RefContext is simple a wrapper type around an Arc<Mutex<Context>> with an identical API to Context. Here are a few examples to demonstrate how chainable contexts work:

use std::time::Duration;
use tokio::time;
use tokio::task;
use tokio_context::context::RefContext;

#[tokio::test]
async fn cancelling_parent_ctx_cancels_child() {
    // Note that we can't simply drop the handle here or the context will be cancelled.
    let (parent_ctx, parent_handle) = RefContext::new();
    let (mut ctx, _handle) = Context::with_parent(&parent_ctx, None);

    parent_handle.cancel();

    // Cancelling a parent will cancel the child context.
    tokio::select! {
        _ = ctx.done() => assert!(true),
        _ = tokio::time::sleep(Duration::from_millis(15)) => assert!(false),
    }
}

#[tokio::test]
async fn cancelling_child_ctx_doesnt_cancel_parent() {
    // Note that we can't simply drop the handle here or the context will be cancelled.
    let (mut parent_ctx, _parent_handle) = RefContext::new();
    let (_ctx, handle) = Context::with_parent(&parent_ctx, None);

    handle.cancel();

    // Cancelling a child will not cancel the parent context.
    tokio::select! {
        _ = parent_ctx.done() => assert!(false),
        _ = async {} => assert!(true),
    }
}

#[tokio::test]
async fn parent_timeout_cancels_child() {
    // Note that we can't simply drop the handle here or the context will be cancelled.
    let (parent_ctx, _parent_handle) = RefContext::with_timeout(Duration::from_millis(5));
    let (mut ctx, _handle) =
        Context::with_parent(&parent_ctx, Some(Duration::from_millis(10)));

    tokio::select! {
        _ = ctx.done() => assert!(true),
        _ = tokio::time::sleep(Duration::from_millis(7)) => assert!(false),
    }
}

Implementations

impl RefContext

pub fn new() -> (RefContext, Handle)

Builds a new RefContext. The done method returns a future that will complete when either the handle is cancelled, or when the optional timeout has elapsed.

pub fn with_timeout(timeout: Duration) -> (RefContext, Handle)

Builds a new Context. The done method returns a future that will complete when either the handle is cancelled, or when the supplied timeout has elapsed.

pub fn with_parent( parent_ctx: &RefContext, timeout: Option<Duration>, ) -> (RefContext, Handle)

Builds a new RefContext, chained to a parent context. When done is called off a chained context it will return a future that will complete when either the handle is cancelled, the optional timeout has elapsed, the parent context is cancelled, or the optional parent timeout has elapsed.

pub fn done(&mut self) -> Pin<Box<dyn Future<Output = ()> + '_>>

Blocks until either the provided timeout elapses, or a cancel signal is received from calling cancel on the Handle that was returned during initial construction.

Trait Implementations

impl Clone for RefContext

fn clone(&self) -> RefContext

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl From<Context> for RefContext

fn from(ctx: Context) -> Self

Converts to this type from the input type.