Trait Context

pub trait Context:
    Clone
    + Send
    + Sync {
    type SubContext: Context;

    // Required methods
    fn timer(&self) -> Timer;
    fn spawn<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Self::SubContext> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn spawn_with_timeout<'life0, 'async_trait>(
        &'life0 self,
        timeout: Duration,
    ) -> Pin<Box<dyn Future<Output = Self::SubContext> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided methods
    fn name<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Name> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn deadline<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Option<Instant>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn cancel<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn is_cancelled<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn is_timeout<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn error<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Option<Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn spawn_in_seconds<'life0, 'async_trait>(
        &'life0 self,
        secs: u64,
    ) -> Pin<Box<dyn Future<Output = Self::SubContext> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn spawn_in_milliseconds<'life0, 'async_trait>(
        &'life0 self,
        millis: u64,
    ) -> Pin<Box<dyn Future<Output = Self::SubContext> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn handle<'a, 'life0, 'async_trait, Fut, T>(
        &'life0 self,
        fut: Fut,
    ) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'async_trait>>
       where Fut: Future<Output = T> + Send + 'a + 'async_trait,
             T: 'async_trait,
             Self: 'async_trait,
             'a: 'async_trait,
             'life0: 'async_trait { ... }
    fn handle_result<'a, 'life0, 'async_trait, Fut, T, E>(
        &'life0 self,
        fut: Fut,
    ) -> Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'async_trait>>
       where Fut: Future<Output = Result<T, E>> + Send + 'a + 'async_trait,
             E: From<Error> + 'async_trait,
             T: 'async_trait,
             Self: 'async_trait,
             'a: 'async_trait,
             'life0: 'async_trait { ... }
}

The Context trait defines the required methods for Context. It can define a duration, be cancellable, and immediately cancel async functions if the processing time exceeds the allowed duration without being cancelled. Additionally, the Context can spawn child contexts.

Examples

use context_async::{Context, Timer};
async fn my_function() {}

let timer = Timer::background(); // a new context without duration limit///
timer.handle(my_function()).await.unwrap();

In addition to using handle, you can also handle it with the future.with() method by simply importing the With trait.

use context_async::{With, Context, Timer};
async fn my_function() {}

let timer = Timer::todo(); // same as background().
my_function()
    .with(timer)
    .await
    .unwrap();

Required Associated Types

type SubContext: Context

Required Methods

fn timer(&self) -> Timer

return the basic Timer.

fn spawn<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Self::SubContext> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

spawn a new child context.

When the parent (self) is cancelled (call by Self::cancel), the child context will be cancelled too.

Example

use context_async::{Context, Timer};

tokio_test::block_on(async {
let ctx = Timer::background();
let child = ctx.spawn().await;
let child_of_child = child.spawn().await;

ctx.cancel().await; // <- parent is cancelled.

assert!(child.is_cancelled().await); // the child is cancelled too.
assert!(child_of_child.is_cancelled().await); // also cancelled.
});

fn spawn_with_timeout<'life0, 'async_trait>( &'life0 self, timeout: Duration, ) -> Pin<Box<dyn Future<Output = Self::SubContext> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

spawn a new child context, with a new timeout parameter.

Same as Self::spawn, when the parent (self) is cancelled (call by Self::cancel), the child context will be cancelled too.

The expire_at instant should not be longer than the parent’s expire_at.

Note

see Self::spawn for more examples.

Provided Methods

fn name<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Name> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Available on crate feature name only.

return the name of this context

fn deadline<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Option<Instant>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

return the deadline time::Instant of this context. return None when this context doesn’t have deadline.

fn cancel<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

cancel this context, then cancel all its childs.

fn is_cancelled<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

check whether this context is cancelled or not.

fn is_timeout<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

check whether this context is timeout or not.

fn error<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Option<Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

check whether there is an Error in context.

fn spawn_in_seconds<'life0, 'async_trait>( &'life0 self, secs: u64, ) -> Pin<Box<dyn Future<Output = Self::SubContext> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

spawn a new child context, with a new timeout parameter in seconds.

fn spawn_in_milliseconds<'life0, 'async_trait>( &'life0 self, millis: u64, ) -> Pin<Box<dyn Future<Output = Self::SubContext> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

spawn a new child context, with a new timeout parameter in milliseconds.

fn handle<'a, 'life0, 'async_trait, Fut, T>( &'life0 self, fut: Fut, ) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'async_trait>>

where Fut: Future<Output = T> + Send + 'a + 'async_trait, T: 'async_trait, Self: 'async_trait, 'a: 'async_trait, 'life0: 'async_trait,

handle a future

Examples

use context_async::{Context, Timer};

 let ctx = Timer::background();
 let task = tokio::time::sleep(tokio::time::Duration::from_secs(1));

 ctx.handle(task).await.unwrap();

fn handle_result<'a, 'life0, 'async_trait, Fut, T, E>( &'life0 self, fut: Fut, ) -> Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'async_trait>>

where Fut: Future<Output = Result<T, E>> + Send + 'a + 'async_trait, E: From<Error> + 'async_trait, T: 'async_trait, Self: 'async_trait, 'a: 'async_trait, 'life0: 'async_trait,

handle a future that returns Result<T, E>.

Note

E is user-defined error, which implements From<Error>.

Examples

use context_async::{Context, Timer};

#[derive(Debug, Clone)]
struct MyError;

impl From<context_async::Error> for MyError {
    fn from(value: context_async::Error) -> Self {
        MyError
    }
}

async fn my_func() -> Result<u8, MyError> {
    Ok(42)
}

let ctx = Timer::background();
let task = my_func();
let _ = ctx.handle_result(task).await;

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T: Context> Context for &T

type SubContext = <T as Context>::SubContext

fn timer(&self) -> Timer

fn spawn<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = T::SubContext> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn spawn_with_timeout<'life0, 'async_trait>( &'life0 self, timeout: Duration, ) -> Pin<Box<dyn Future<Output = T::SubContext> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Implementors

impl Context for Timer

type SubContext = Timer