Struct tokio_util::sync::CancellationToken

pub struct CancellationToken { /* private fields */ }

A token which can be used to signal a cancellation request to one or more tasks.

Tasks can call CancellationToken::cancelled() in order to obtain a Future which will be resolved when cancellation is requested.

Cancellation can be requested through the CancellationToken::cancel method.

Examples

use tokio::select;
use tokio_util::sync::CancellationToken;

#[tokio::main]
async fn main() {
    let token = CancellationToken::new();
    let cloned_token = token.clone();

    let join_handle = tokio::spawn(async move {
        // Wait for either cancellation or a very long time
        select! {
            _ = cloned_token.cancelled() => {
                // The token was cancelled
                5
            }
            _ = tokio::time::sleep(std::time::Duration::from_secs(9999)) => {
                99
            }
        }
    });

    tokio::spawn(async move {
        tokio::time::sleep(std::time::Duration::from_millis(10)).await;
        token.cancel();
    });

    assert_eq!(5, join_handle.await.unwrap());
}

Implementations

impl CancellationToken

pub fn new() -> CancellationToken

Creates a new CancellationToken in the non-cancelled state.

pub fn child_token(&self) -> CancellationToken

Creates a CancellationToken which will get cancelled whenever the current token gets cancelled.

If the current token is already cancelled, the child token will get returned in cancelled state.

Examples

use tokio::select;
use tokio_util::sync::CancellationToken;

#[tokio::main]
async fn main() {
    let token = CancellationToken::new();
    let child_token = token.child_token();

    let join_handle = tokio::spawn(async move {
        // Wait for either cancellation or a very long time
        select! {
            _ = child_token.cancelled() => {
                // The token was cancelled
                5
            }
            _ = tokio::time::sleep(std::time::Duration::from_secs(9999)) => {
                99
            }
        }
    });

    tokio::spawn(async move {
        tokio::time::sleep(std::time::Duration::from_millis(10)).await;
        token.cancel();
    });

    assert_eq!(5, join_handle.await.unwrap());
}

pub fn cancel(&self)

Cancel the CancellationToken and all child tokens which had been derived from it.

This will wake up all tasks which are waiting for cancellation.

pub fn is_cancelled(&self) -> bool

Returns true if the CancellationToken had been cancelled

pub fn cancelled(&self) -> WaitForCancellationFuture<'_>

Returns a Future that gets fulfilled when cancellation is requested.

pub fn drop_guard(self) -> DropGuard

Creates a DropGuard for this token.

Returned guard will cancel this token (and all its children) on drop unless disarmed.

Trait Implementations

impl Clone for CancellationToken

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for CancellationToken

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

Formats the value using the given formatter.

impl Default for CancellationToken

fn default() -> CancellationToken

Returns the “default value” for a type.

impl Drop for CancellationToken

fn drop(&mut self)

Executes the destructor for this type.

impl Send for CancellationToken

impl Sync for CancellationToken