From b3a14483bf5efa1b5cf75af27f6ef0770f4c5689 Mon Sep 17 00:00:00 2001 From: Qi Date: Thu, 19 Jun 2025 06:32:41 +0800 Subject: [PATCH] sync: improve docs of `tokio_util::sync::CancellationToken` (#7408) Co-authored-by: Alice Ryhl --- tokio-util/src/sync/cancellation_token.rs | 42 ++++++++++++------- .../src/sync/cancellation_token/guard.rs | 4 +- .../src/sync/cancellation_token/guard_ref.rs | 7 +++- 3 files changed, 35 insertions(+), 18 deletions(-) diff --git a/tokio-util/src/sync/cancellation_token.rs b/tokio-util/src/sync/cancellation_token.rs index 64cff2199..c04d8dc19 100644 --- a/tokio-util/src/sync/cancellation_token.rs +++ b/tokio-util/src/sync/cancellation_token.rs @@ -1,4 +1,4 @@ -//! An asynchronously awaitable `CancellationToken`. +//! An asynchronously awaitable [`CancellationToken`]. //! The token allows to signal a cancellation request to one or more tasks. pub(crate) mod guard; pub(crate) mod guard_ref; @@ -112,7 +112,7 @@ impl core::fmt::Debug for CancellationToken { } impl Clone for CancellationToken { - /// Creates a clone of the `CancellationToken` which will get cancelled + /// Creates a clone of the [`CancellationToken`] which will get cancelled /// whenever the current token gets cancelled, and vice versa. fn clone(&self) -> Self { tree_node::increase_handle_refcount(&self.inner); @@ -135,15 +135,15 @@ impl Default for CancellationToken { } impl CancellationToken { - /// Creates a new `CancellationToken` in the non-cancelled state. + /// Creates a new [`CancellationToken`] in the non-cancelled state. pub fn new() -> CancellationToken { CancellationToken { inner: Arc::new(tree_node::TreeNode::new()), } } - /// Creates a `CancellationToken` which will get cancelled whenever the - /// current token gets cancelled. Unlike a cloned `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 @@ -206,12 +206,18 @@ impl CancellationToken { tree_node::is_cancelled(&self.inner) } - /// Returns a `Future` that gets fulfilled when cancellation is requested. + /// Returns a [`Future`] that gets fulfilled when cancellation is requested. + /// + /// Equivalent to: + /// + /// ```ignore + /// async fn cancelled(&self); + /// ``` /// /// The future will complete immediately if the token is already cancelled /// when this method is called. /// - /// # Cancel safety + /// # Cancellation safety /// /// This method is cancel safe. pub fn cancelled(&self) -> WaitForCancellationFuture<'_> { @@ -221,7 +227,13 @@ impl CancellationToken { } } - /// Returns a `Future` that gets fulfilled when cancellation is requested. + /// Returns a [`Future`] that gets fulfilled when cancellation is requested. + /// + /// Equivalent to: + /// + /// ```ignore + /// async fn cancelled_owned(self); + /// ``` /// /// The future will complete immediately if the token is already cancelled /// when this method is called. @@ -229,14 +241,14 @@ impl CancellationToken { /// The function takes self by value and returns a future that owns the /// token. /// - /// # Cancel safety + /// # Cancellation safety /// /// This method is cancel safe. pub fn cancelled_owned(self) -> WaitForCancellationFutureOwned { WaitForCancellationFutureOwned::new(self) } - /// Creates a `DropGuard` for this token. + /// Creates a [`DropGuard`] for this token. /// /// Returned guard will cancel this token (and all its children) on drop /// unless disarmed. @@ -244,7 +256,7 @@ impl CancellationToken { DropGuard { inner: Some(self) } } - /// Creates a `DropGuardRef` for this token. + /// Creates a [`DropGuardRef`] for this token. /// /// Returned guard will cancel this token (and all its children) on drop /// unless disarmed. @@ -253,10 +265,10 @@ impl CancellationToken { } /// 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 + /// unless the [`CancellationToken`] is cancelled. In that case the function returns /// `None` and the future gets dropped. /// - /// # Cancel safety + /// # Cancellation safety /// /// This method is only cancel safe if `fut` is cancel safe. pub async fn run_until_cancelled(&self, fut: F) -> Option @@ -299,12 +311,12 @@ impl CancellationToken { } /// 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 + /// unless the [`CancellationToken`] is cancelled. In that case the function returns /// `None` and the future gets dropped. /// /// The function takes self by value and returns a future that owns the token. /// - /// # Cancel safety + /// # Cancellation safety /// /// This method is only cancel safe if `fut` is cancel safe. pub async fn run_until_cancelled_owned(self, fut: F) -> Option diff --git a/tokio-util/src/sync/cancellation_token/guard.rs b/tokio-util/src/sync/cancellation_token/guard.rs index 54ed7ea2e..f0b6101bd 100644 --- a/tokio-util/src/sync/cancellation_token/guard.rs +++ b/tokio-util/src/sync/cancellation_token/guard.rs @@ -1,7 +1,9 @@ use crate::sync::CancellationToken; /// A wrapper for cancellation token which automatically cancels -/// it on drop. It is created using `drop_guard` method on the `CancellationToken`. +/// it on drop. It is created using [`drop_guard`] method on the [`CancellationToken`]. +/// +/// [`drop_guard`]: CancellationToken::drop_guard #[derive(Debug)] pub struct DropGuard { pub(super) inner: Option, diff --git a/tokio-util/src/sync/cancellation_token/guard_ref.rs b/tokio-util/src/sync/cancellation_token/guard_ref.rs index b48fd19de..20b8fa324 100644 --- a/tokio-util/src/sync/cancellation_token/guard_ref.rs +++ b/tokio-util/src/sync/cancellation_token/guard_ref.rs @@ -1,9 +1,12 @@ use crate::sync::CancellationToken; /// A wrapper for cancellation token which automatically cancels -/// it on drop. It is created using `drop_guard_ref` method on the `CancellationToken`. +/// it on drop. It is created using [`drop_guard_ref`] method on the [`CancellationToken`]. /// -/// This is a `ref` version of `DropGuard` +/// This is a borrowed version of [`DropGuard`]. +/// +/// [`drop_guard_ref`]: CancellationToken::drop_guard_ref +/// [`DropGuard`]: super::DropGuard #[derive(Debug)] pub struct DropGuardRef<'a> { pub(super) inner: Option<&'a CancellationToken>,