Struct CancellationToken

Namespace

System.Threading

Assembly

System.Threading.dll

Propagates notification that operations should be canceled.

public struct CancellationToken

Inherited Members

object.ToString()

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetType()

Remarks

A CancellationToken may be created directly in an unchangeable canceled or non-canceled state using the CancellationToken's constructors. However, to have a CancellationToken that can change from a non-canceled to a canceled state, CancellationTokenSource must be used. CancellationTokenSource exposes the associated CancellationToken that may be canceled by the source through its Token property.

Once canceled, a token may not transition to a non-canceled state, and a token whose CanBeCanceled is false will never change to one that can be canceled.

All members of this struct are thread-safe and may be used concurrently from multiple threads.

Constructors

CancellationToken(bool)

Initializes the CancellationToken.

public CancellationToken(bool canceled)

Parameters

canceled bool

The canceled state for the token.

Remarks

Tokens created with this constructor will remain in the canceled state specified by the canceled parameter. If canceled is false, both CanBeCanceled and IsCancellationRequested will be false. If canceled is true, both CanBeCanceled and IsCancellationRequested will be true.

Properties

CanBeCanceled

Gets whether this token is capable of being in the canceled state.

public bool CanBeCanceled { get; }

Property Value

bool

Remarks

If CanBeCanceled returns false, it is guaranteed that the token will never transition into a canceled state, meaning that IsCancellationRequested will never return true.

IsCancellationRequested

Gets whether cancellation has been requested for this token.

public bool IsCancellationRequested { get; }

Property Value

bool

Whether cancellation has been requested for this token.

Remarks

This property indicates whether cancellation has been requested for this token, either through the token initially being construted in a canceled state, or through calling Cancel on the token's associated CancellationTokenSource.

If this property is true, it only guarantees that cancellation has been requested. It does not guarantee that every registered handler 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.

None

Returns an empty CancellationToken value.

public static CancellationToken None { get; }

Property Value

CancellationToken

Remarks

The CancellationToken value returned by this property will be non-cancelable by default.

WaitHandle

Gets a WaitHandle that is signaled when the token is canceled.

public WaitHandle WaitHandle { get; }

Property Value

WaitHandle

Remarks

Accessing this property causes a WaitHandle to be instantiated. It is preferable to only use this property when necessary, and to then dispose the associated CancellationTokenSource instance at the earliest opportunity (disposing the source will dispose of this allocated handle). The handle should not be closed or disposed directly.

Exceptions

ObjectDisposedException

The associated CancellationTokenSource has been disposed.

Methods

Equals(object)

Determines whether the current CancellationToken instance is equal to the specified object.

public override bool Equals(object other)

Parameters

other object

The other object to which to compare this instance.

Returns

bool

True if other is a CancellationToken and if the two instances are equal; otherwise, false. Two tokens are equal if they are associated with the same CancellationTokenSource or if they were both constructed from public CancellationToken constructors and their IsCancellationRequested values are equal.

Exceptions

ObjectDisposedException

An associated CancellationTokenSource has been disposed.

Equals(CancellationToken)

Determines whether the current CancellationToken instance is equal to the specified token.

public bool Equals(CancellationToken other)

Parameters

other CancellationToken

The other CancellationToken to which to compare this instance.

Returns

bool

True if the instances are equal; otherwise, false. Two tokens are equal if they are associated with the same CancellationTokenSource or if they were both constructed from public CancellationToken constructors and their IsCancellationRequested values are equal.

GetHashCode()

Serves as a hash function for a CancellationToken.

public override int GetHashCode()

Returns

int

A hash code for the current CancellationToken instance.

Register(Action)

Registers a delegate that will be called when this CancellationToken is canceled.

public CancellationTokenRegistration Register(Action callback)

Parameters

callback Action

The delegate to be executed when the CancellationToken is canceled.

Returns

CancellationTokenRegistration

The CancellationTokenRegistration instance that can be used to deregister the callback.

Remarks

If this token is already in the canceled state, the delegate will be run immediately and synchronously. Any exception the delegate generates will be propagated out of this method call.

The current System.Threading.ExecutionContext, if one exists, will be captured along with the delegate and will be used when executing it.

Exceptions

ArgumentNullException

callback is null.

ThrowIfCancellationRequested()

Throws a OperationCanceledException if this token has had cancellation requested.

public void ThrowIfCancellationRequested()

Remarks

This method provides functionality equivalent to:

if (token.IsCancellationRequested) 
   throw new OperationCanceledException(token);

Exceptions

ObjectDisposedException

The associated CancellationTokenSource has been disposed.