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. Unlike a cloned CancellationToken
,
cancelling a child token does not cancel the parent token.
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.
sourcepub async fn run_until_cancelled<F>(&self, fut: F) -> Option<F::Output>where
F: Future,
pub async fn run_until_cancelled<F>(&self, fut: F) -> Option<F::Output>where
F: Future,
Runs a future to completion and returns its result wrapped inside of an Option
unless the CancellationToken
is cancelled. In that case the function returns
None
and the future gets dropped.
§Cancel safety
This method is only cancel safe if fut
is cancel safe.
Trait Implementations§
source§impl Clone for CancellationToken
impl Clone for CancellationToken
source§impl Debug for CancellationToken
impl Debug for CancellationToken
source§impl Default for CancellationToken
impl Default for CancellationToken
source§fn default() -> CancellationToken
fn default() -> CancellationToken
source§impl Drop for CancellationToken
impl Drop for CancellationToken
impl RefUnwindSafe for CancellationToken
impl UnwindSafe for CancellationToken
Auto Trait Implementations§
impl Freeze for CancellationToken
impl Send for CancellationToken
impl Sync for CancellationToken
impl Unpin for CancellationToken
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)