Meziantou.FrameworkResettableCancellationTokenSource Class
Represents a cancellation token source that can be reset to its initial state.
public sealed class ResettableCancellationTokenSource : IAsyncDisposable, IDisposableRemarks
All members are safe to call concurrently. Note that the callbacks registered on ResettableCancellationTokenSource.Token run while the internal lock is held, so a callback must not block waiting on another thread that uses the same instance. ResettableCancellationTokenSource.DisposeAsync is the exception: it runs them on another thread and does not hold the lock while they complete.
ResettableCancellationTokenSource.Reset reuses the underlying CancellationTokenSource when it can, so whether a CancellationToken obtained before the reset belongs to the previous generation depends on the state of that source:
- When cancellation has already been requested - through
ResettableCancellationTokenSource.Cancel, through an elapsedResettableCancellationTokenSource.CancelAfterdelay, or becauseResettableCancellationTokenSourceOptions.CancelOnResetis set - the source cannot be reused and is replaced. The previous token stays canceled and never reacts to a laterResettableCancellationTokenSource.Cancel. - Otherwise the same source is reused, so the previous token is the very token
ResettableCancellationTokenSource.Tokenreturns afterwards and it does react to a laterResettableCancellationTokenSource.Cancel. The reset also removes the callbacks already registered on that token, which are never invoked, and disarms a pendingResettableCancellationTokenSource.CancelAfterdelay.
Read ResettableCancellationTokenSource.Token again after resetting rather than relying on either behavior.
Example
using var cts = new ResettableCancellationTokenSource(cancelOnResetAndDispose: true);
// Use the token
var token = cts.Token;
await Task.Delay(1, token);
// Reset to reuse: the previous token is canceled, read Token again to get a new one
cts.Reset();
Assert.True(token.IsCancellationRequested);
await Task.Delay(1, cts.Token);- Implements
Constructors
| Name | Description |
|---|---|
| ResettableCancellationTokenSource(ResettableCancellationTokenSourceOptions) | Initializes a new instance of the ResettableCancellationTokenSource class with the specified options. |
| ResettableCancellationTokenSource(bool) | Initializes a new instance of the ResettableCancellationTokenSource class. |
ResettableCancellationTokenSource overloads
ResettableCancellationTokenSource(ResettableCancellationTokenSourceOptions)
ResettableCancellationTokenSource.csInitializes a new instance of the ResettableCancellationTokenSource class with the specified options.
public ResettableCancellationTokenSource(ResettableCancellationTokenSourceOptions options)Parameters
optionsResettableCancellationTokenSourceOptions- Options that control the behavior when resetting or disposing.
ResettableCancellationTokenSource(bool)
ResettableCancellationTokenSource.csInitializes a new instance of the ResettableCancellationTokenSource class.
public ResettableCancellationTokenSource(bool cancelOnResetAndDispose)Parameters
cancelOnResetAndDisposebooltrueto cancel the token when resetting or disposing; otherwise,false.
Properties
| Name | Description |
|---|---|
| IsCancellationRequested | Gets whether cancellation has been requested for this token source. |
| Token | Gets the cancellation token associated with this ResettableCancellationTokenSource. |
IsCancellationRequested
ResettableCancellationTokenSource.csGets the cancellation token associated with this ResettableCancellationTokenSource.
public CancellationToken Token { get; }Property value
Methods
| Name | Description |
|---|---|
| Cancel() | Communicates a request for cancellation. |
| CancelAfter(TimeSpan) | Schedules a cancel operation on this ResettableCancellationTokenSource after the specified time span. |
| Dispose() | Releases the resources used by this ResettableCancellationTokenSource. |
| DisposeAsync() | Releases the resources used by this ResettableCancellationTokenSource, without running the cancellation callbacks on the calling thread. |
| Reset() | Resets the cancellation token source to its initial state. |
Communicates a request for cancellation.
public void Cancel()CancelAfter(TimeSpan)
ResettableCancellationTokenSource.csSchedules a cancel operation on this ResettableCancellationTokenSource after the specified time span.
Parameters
delayTimeSpan- The time span to wait before canceling this
ResettableCancellationTokenSource.
Dispose()
ResettableCancellationTokenSource.csReleases the resources used by this ResettableCancellationTokenSource.
public void Dispose()Exceptions
AggregateException- A callback registered on the current
ResettableCancellationTokenSource.Tokenthrew.
Remarks
The underlying CancellationTokenSource is disposed even when a cancellation callback throws: the exception raised by CancellationTokenSource.Cancel propagates to the caller only after the resources are released. Subsequent calls do nothing.
DisposeAsync()
ResettableCancellationTokenSource.csReleases the resources used by this ResettableCancellationTokenSource, without running the cancellation callbacks on the calling thread.
public ValueTask DisposeAsync()Returns
Exceptions
AggregateException- A callback registered on the current
ResettableCancellationTokenSource.Tokenthrew.
Remarks
Unlike ResettableCancellationTokenSource.Dispose, this method relies on CancellationTokenSource.CancelAsync, so the callbacks registered on ResettableCancellationTokenSource.Token run on another thread and are awaited instead of blocking the caller. A callback is therefore free to use this instance, which is not the case with ResettableCancellationTokenSource.Dispose.
The underlying CancellationTokenSource is disposed even when a callback throws: the exception raised by CancellationTokenSource.CancelAsync propagates to the caller only after the resources are released. Subsequent calls do nothing, whether they go through ResettableCancellationTokenSource.Dispose or this method, but a call made while this one is still awaiting the callbacks returns before the resources are released.
Resets the cancellation token source to its initial state.
public void Reset()Exceptions
ObjectDisposedException- The instance is disposed.
AggregateException- A callback registered on the current
ResettableCancellationTokenSource.Tokenthrew.
Remarks
The underlying CancellationTokenSource is reused when cancellation has not been requested, so the token read before the reset can be the very token ResettableCancellationTokenSource.Token returns afterwards. See the remarks on ResettableCancellationTokenSource for the exact behavior.
The instance is reset even when a cancellation callback throws: the exception raised by CancellationTokenSource.Cancel propagates to the caller only after a fresh ResettableCancellationTokenSource.Token is available. A callback that disposes this instance wins, and the reset is abandoned.