Struct tokio_util::sync::CancellationToken
source · pub struct CancellationToken { /* private fields */ }
Expand description
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§
source§impl CancellationToken
impl CancellationToken
sourcepub fn new() -> CancellationToken
pub fn new() -> CancellationToken
Creates a new CancellationToken in the non-cancelled state.
sourcepub fn child_token(&self) -> CancellationToken
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());
}
sourcepub fn cancel(&self)
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.
Be aware that cancellation is not an atomic operation. It is possible
for another thread running in parallel with a call to cancel
to first
receive true
from is_cancelled
on one child node, and then receive
false
from is_cancelled
on another child node. However, once the
call to cancel
returns, all child nodes have been fully cancelled.
sourcepub fn is_cancelled(&self) -> bool
pub fn is_cancelled(&self) -> bool
Returns true
if the CancellationToken
is cancelled.
sourcepub fn cancelled(&self) -> WaitForCancellationFuture<'_> ⓘ
pub fn cancelled(&self) -> WaitForCancellationFuture<'_> ⓘ
Returns a Future
that gets fulfilled when cancellation is requested.
The future will complete immediately if the token is already cancelled when this method is called.
Cancel safety
This method is cancel safe.
sourcepub fn cancelled_owned(self) -> WaitForCancellationFutureOwned ⓘ
pub fn cancelled_owned(self) -> WaitForCancellationFutureOwned ⓘ
Returns a Future
that gets fulfilled when cancellation is requested.
The future will complete immediately if the token is already cancelled when this method is called.
The function takes self by value and returns a future that owns the token.
Cancel safety
This method is cancel safe.
sourcepub fn drop_guard(self) -> DropGuard
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.