1- //! An asynchronously awaitable `CancellationToken`.
1+ //! An asynchronously awaitable [ `CancellationToken`] .
22//! The token allows to signal a cancellation request to one or more tasks.
33pub ( crate ) mod guard;
44pub ( crate ) mod guard_ref;
@@ -112,7 +112,7 @@ impl core::fmt::Debug for CancellationToken {
112112}
113113
114114impl Clone for CancellationToken {
115- /// Creates a clone of the `CancellationToken` which will get cancelled
115+ /// Creates a clone of the [ `CancellationToken`] which will get cancelled
116116 /// whenever the current token gets cancelled, and vice versa.
117117 fn clone ( & self ) -> Self {
118118 tree_node:: increase_handle_refcount ( & self . inner ) ;
@@ -135,15 +135,15 @@ impl Default for CancellationToken {
135135}
136136
137137impl CancellationToken {
138- /// Creates a new `CancellationToken` in the non-cancelled state.
138+ /// Creates a new [ `CancellationToken`] in the non-cancelled state.
139139 pub fn new ( ) -> CancellationToken {
140140 CancellationToken {
141141 inner : Arc :: new ( tree_node:: TreeNode :: new ( ) ) ,
142142 }
143143 }
144144
145- /// Creates a `CancellationToken` which will get cancelled whenever the
146- /// current token gets cancelled. Unlike a cloned `CancellationToken`,
145+ /// Creates a [ `CancellationToken`] which will get cancelled whenever the
146+ /// current token gets cancelled. Unlike a cloned [ `CancellationToken`] ,
147147 /// cancelling a child token does not cancel the parent token.
148148 ///
149149 /// If the current token is already cancelled, the child token will get
@@ -206,12 +206,18 @@ impl CancellationToken {
206206 tree_node:: is_cancelled ( & self . inner )
207207 }
208208
209- /// Returns a `Future` that gets fulfilled when cancellation is requested.
209+ /// Returns a [`Future`] that gets fulfilled when cancellation is requested.
210+ ///
211+ /// Equivalent to:
212+ ///
213+ /// ```ignore
214+ /// async fn cancelled(&self);
215+ /// ```
210216 ///
211217 /// The future will complete immediately if the token is already cancelled
212218 /// when this method is called.
213219 ///
214- /// # Cancel safety
220+ /// # Cancellation safety
215221 ///
216222 /// This method is cancel safe.
217223 pub fn cancelled ( & self ) -> WaitForCancellationFuture < ' _ > {
@@ -221,30 +227,36 @@ impl CancellationToken {
221227 }
222228 }
223229
224- /// Returns a `Future` that gets fulfilled when cancellation is requested.
230+ /// Returns a [`Future`] that gets fulfilled when cancellation is requested.
231+ ///
232+ /// Equivalent to:
233+ ///
234+ /// ```ignore
235+ /// async fn cancelled_owned(self);
236+ /// ```
225237 ///
226238 /// The future will complete immediately if the token is already cancelled
227239 /// when this method is called.
228240 ///
229241 /// The function takes self by value and returns a future that owns the
230242 /// token.
231243 ///
232- /// # Cancel safety
244+ /// # Cancellation safety
233245 ///
234246 /// This method is cancel safe.
235247 pub fn cancelled_owned ( self ) -> WaitForCancellationFutureOwned {
236248 WaitForCancellationFutureOwned :: new ( self )
237249 }
238250
239- /// Creates a `DropGuard` for this token.
251+ /// Creates a [ `DropGuard`] for this token.
240252 ///
241253 /// Returned guard will cancel this token (and all its children) on drop
242254 /// unless disarmed.
243255 pub fn drop_guard ( self ) -> DropGuard {
244256 DropGuard { inner : Some ( self ) }
245257 }
246258
247- /// Creates a `DropGuardRef` for this token.
259+ /// Creates a [ `DropGuardRef`] for this token.
248260 ///
249261 /// Returned guard will cancel this token (and all its children) on drop
250262 /// unless disarmed.
@@ -253,10 +265,10 @@ impl CancellationToken {
253265 }
254266
255267 /// Runs a future to completion and returns its result wrapped inside of an `Option`
256- /// unless the `CancellationToken` is cancelled. In that case the function returns
268+ /// unless the [ `CancellationToken`] is cancelled. In that case the function returns
257269 /// `None` and the future gets dropped.
258270 ///
259- /// # Cancel safety
271+ /// # Cancellation safety
260272 ///
261273 /// This method is only cancel safe if `fut` is cancel safe.
262274 pub async fn run_until_cancelled < F > ( & self , fut : F ) -> Option < F :: Output >
@@ -299,12 +311,12 @@ impl CancellationToken {
299311 }
300312
301313 /// Runs a future to completion and returns its result wrapped inside of an `Option`
302- /// unless the `CancellationToken` is cancelled. In that case the function returns
314+ /// unless the [ `CancellationToken`] is cancelled. In that case the function returns
303315 /// `None` and the future gets dropped.
304316 ///
305317 /// The function takes self by value and returns a future that owns the token.
306318 ///
307- /// # Cancel safety
319+ /// # Cancellation safety
308320 ///
309321 /// This method is only cancel safe if `fut` is cancel safe.
310322 pub async fn run_until_cancelled_owned < F > ( self , fut : F ) -> Option < F :: Output >
0 commit comments