Table of Contents

Class CancellationTokenSource

Namespace
System.Threading
Assembly
System.Threading.dll

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 int

The 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 TimeSpan

The 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 bool

Specifies 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 int

The 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 TimeSpan

The 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 bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.