Class CancellationTokenSource
Signals to a CancellationToken that it should be canceled.
public class CancellationTokenSource : IDisposable
- Inheritance
-
CancellationTokenSource
- Implements
- Inherited Members
- Extension Methods
Remarks
CancellationTokenSource is used to instantiate a CancellationToken (via the source's Token property) that can be handed to operations that wish to be notified of cancellation or that can be used to register asynchronous operations for cancellation. That token may have cancellation requested by calling to the source's Cancel method.
All members of this class, except Dispose, are thread-safe and may be used concurrently from multiple threads.
Constructors
CancellationTokenSource()
Initializes the CancellationTokenSource.
public CancellationTokenSource()
CancellationTokenSource(int)
Constructs a CancellationTokenSource that will be canceled after a specified time span.
public CancellationTokenSource(int millisecondsDelay)
Parameters
millisecondsDelay
intThe time span to wait before canceling this CancellationTokenSource
Remarks
The countdown for the millisecondsDelay starts during the call to the constructor. When the millisecondsDelay expires, the constructed CancellationTokenSource is canceled (if it has not been canceled already).
Subsequent calls to CancelAfter will reset the millisecondsDelay for the constructed CancellationTokenSource, if it has not been canceled already.
Exceptions
- ArgumentOutOfRangeException
The exception that is thrown when
millisecondsDelay
is less than -1.
CancellationTokenSource(TimeSpan)
Constructs a CancellationTokenSource that will be canceled after a specified time span.
public CancellationTokenSource(TimeSpan delay)
Parameters
delay
TimeSpanThe time span to wait before canceling this CancellationTokenSource
Remarks
The countdown for the delay starts during the call to the constructor. When the delay expires, the constructed CancellationTokenSource is canceled, if it has not been canceled already.
Subsequent calls to CancelAfter will reset the delay for the constructed CancellationTokenSource, if it has not been canceled already.
Exceptions
- ArgumentOutOfRangeException
The exception that is thrown when
delay
is less than -1 or greater than Int32.MaxValue.
Properties
IsCancellationRequested
Gets whether cancellation has been requested for this CancellationTokenSource.
public bool IsCancellationRequested { get; }
Property Value
- bool
Whether cancellation has been requested for this CancellationTokenSource.
Remarks
This property indicates whether cancellation has been requested for this token source, such as due to a call to its Cancel method.
If this property returns true, it only guarantees that cancellation has been requested. It does not guarantee that every handler registered with the corresponding token has finished executing, nor that cancellation requests have finished propagating to all registered handlers. Additional synchronization may be required, particularly in situations where related objects are being canceled concurrently.
Token
Gets the CancellationToken associated with this CancellationTokenSource.
public CancellationToken Token { get; }
Property Value
- CancellationToken
The CancellationToken associated with this CancellationTokenSource.
Exceptions
- ObjectDisposedException
The token source has been disposed.
Methods
Cancel()
Communicates a request for cancellation.
public void Cancel()
Remarks
The associated CancellationToken will be notified of the cancellation and will transition to a state where IsCancellationRequested returns true. Any callbacks or cancelable operations registered with the CancellationToken will be executed.
Cancelable operations and callbacks registered with the token should not throw exceptions. However, this overload of Cancel will aggregate any exceptions thrown into a System.AggregateException, such that one callback throwing an exception will not prevent other registered callbacks from being executed.
The System.Threading.ExecutionContext that was captured when each callback was registered will be reestablished when the callback is invoked.
Exceptions
- AggregateException
An aggregate exception containing all the exceptions thrown by the registered callbacks on the associated CancellationToken.
- ObjectDisposedException
This CancellationTokenSource has been disposed.
Cancel(bool)
Communicates a request for cancellation.
public void Cancel(bool throwOnFirstException)
Parameters
throwOnFirstException
boolSpecifies whether exceptions should immediately propagate.
Remarks
The associated CancellationToken will be notified of the cancellation and will transition to a state where IsCancellationRequested returns true. Any callbacks or cancelable operations registered with the CancellationToken will be executed.
Cancelable operations and callbacks registered with the token should not throw exceptions.
If throwOnFirstException
is true, an exception will immediately propagate out of the
call to Cancel, preventing the remaining callbacks and cancelable operations from being processed.
If throwOnFirstException
is false, this overload will aggregate any
exceptions thrown into a System.AggregateException,
such that one callback throwing an exception will not prevent other registered callbacks from being executed.
The System.Threading.ExecutionContext that was captured when each callback was registered will be reestablished when the callback is invoked.
Exceptions
- AggregateException
An aggregate exception containing all the exceptions thrown by the registered callbacks on the associated CancellationToken.
- ObjectDisposedException
This CancellationTokenSource has been disposed.
CancelAfter(int)
Schedules a Cancel operation on this CancellationTokenSource.
public void CancelAfter(int millisecondsDelay)
Parameters
millisecondsDelay
intThe time span to wait before canceling this CancellationTokenSource.
Remarks
The countdown for the millisecondsDelay starts during this call. When the millisecondsDelay expires, this CancellationTokenSource is canceled, if it has not been canceled already.
Subsequent calls to CancelAfter will reset the millisecondsDelay for this CancellationTokenSource, if it has not been canceled already.
Exceptions
- ObjectDisposedException
The exception thrown when this CancellationTokenSource has been disposed.
- ArgumentOutOfRangeException
The exception thrown when
millisecondsDelay
is less than -1.
CancelAfter(TimeSpan)
Schedules a Cancel operation on this CancellationTokenSource.
public void CancelAfter(TimeSpan delay)
Parameters
delay
TimeSpanThe time span to wait before canceling this CancellationTokenSource.
Remarks
The countdown for the delay starts during this call. When the delay expires, this CancellationTokenSource is canceled, if it has not been canceled already.
Subsequent calls to CancelAfter will reset the delay for this CancellationTokenSource, if it has not been canceled already.
Exceptions
- ObjectDisposedException
The exception thrown when this CancellationTokenSource has been disposed.
- ArgumentOutOfRangeException
The exception thrown when
delay
is less than -1 or greater than Int32.MaxValue.
Dispose()
Releases the resources used by this CancellationTokenSource.
public void Dispose()
Remarks
This method is not thread-safe for any other concurrent calls.
Dispose(bool)
Releases the unmanaged resources used by the CancellationTokenSource class and optionally releases the managed resources.
protected virtual void Dispose(bool disposing)
Parameters
disposing
booltrue to release both managed and unmanaged resources; false to release only unmanaged resources.