xtd::threading::cancellation_token Class Reference

Inheritance diagram for xtd::threading::cancellation_token:

Definition

Propagates notification that operations should be canceled.

class core_export_ cancellation_token : public xtd::object

Inheritance

xtd::object → xtd::threading::cancellation_token

Header

#include <xtd/threading/cancellation_token>

Namespace

xtd::threading

Library

xtd.core

Examples

The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. To handle the possible cancellation of the operation, the example instantiates a xtd::threading::cancellation_token_source object that generates a cancellation token that's passed to a xtd::threading::tasks::task_factory object. In turn, the xtd::threading::tasks::task_factory object passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The xtd::threading::tasks::task_factory::continue_when_all<antecedent_result_t,result_t>(xtd::array<xtd::threading::tasks::task<antecedent_result_t>>, xtd::func<xtd::array<xtd::threading::tasks::task<antecedent_tesult_t>>,TResult>, cancellation_token) method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not completed because it was cancelled, the xtd::threading::tasks::task_factory::continue_when_all method throws an exception.

Remarks

A xtd::threading::cancellation_token enables cooperative cancellation between threads, thread pool work items, or xtd::threading::taks::task objects. You create a cancellation token by instantiating a xtd::threading::cancellation_token_source object, which manages cancellation tokens retrieved from its xtd::threading::cancellation_token_source::token property. You then pass the cancellation token to any number of threads, tasks, or operations that should receive notice of cancellation. The token cannot be used to initiate cancellation. When the owning object calls xtd::threading::cancellation_token_source.cancel, the xtd::threading::cancellation_token::is_cancellation_requested property on every copy of the cancellation token is set to true. The objects that receive the notification can respond in whatever manner is appropriate.

Public Fields
static cancellation_token	none
	Represents an empty xtd::threading::cancellation_token value.

Public Constructors
	cancellation_token (bool canceled)
	Initializes the xtd::threading::cancellation_token.

Public Properties
bool	can_be_canceled () const noexcept
	Gets whether this token is capable of being in the canceled state.
bool	is_cancellation_requested () const noexcept
	Gets whether cancellation has been requested for this token.
threading::wait_handle &	wait_handle () noexcept
	Gets a xtd::threading::wait_handle that is signaled when the token is canceled.

Public Methods
bool	equals (const object &obj) const noexcept override
	Determines whether the specified object is equal to the current object.
bool	equals (const cancellation_token &other) const noexcept override
	Determines whether the specified object is equal to the current object.
xtd::size	get_hash_code () const noexcept override
	Serves as a hash function for a particular type.
void	throw_if_cancellation_requested () const
	Throws a xtd::operation_canceled_exception if this token has had cancellation requested.

Additional Inherited Members
	object ()=default
	Create a new instance of the ultimate base class object.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.
virtual bool	equals (const cancellation_token &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type.
template<class object_a_t, class object_b_t>
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t, class object_b_t>
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

cancellation_token()

xtd::threading::cancellation_token::cancellation_token

(

bool

canceled

)

Initializes the xtd::threading::cancellation_token.

Parameters

canceled

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 xtd::threading::cancellation_token::can_be_canceled and xtd::threading::cancellation_token::is_cancellation_requested will be false.

If canceled is true, both xtd::threading::cancellation_token::can_be_canceled and xtd::threading::cancellation_token::is_cancellation_requested will be true.

Member Function Documentation

can_be_canceled()

bool xtd::threading::cancellation_token::can_be_canceled ( ) const

noexcept

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

Returns

true if this token is capable of being in the canceled state; otherwise, false.

is_cancellation_requested()

bool xtd::threading::cancellation_token::is_cancellation_requested ( ) const

noexcept

Gets whether cancellation has been requested for this token.

Returns

true if cancellation has been requested for this token; otherwise, false.

Remarks

This property indicates whether cancellation has been requested for this token, either through the token initially being constructed in a canceled state, or through calling xtd::threading::cancellation_token_source::cancel on the token's associated xtd::threading::cancellation_token_source.

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.

wait_handle()

threading::wait_handle & xtd::threading::cancellation_token::wait_handle ( )

noexcept

Gets a xtd::threading::wait_handle that is signaled when the token is canceled.

Remarks

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

equals() [1/2]

bool xtd::threading::cancellation_token::equals ( const object & obj ) const

overridevirtualnoexcept

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

Parameters

obj	The object to compare with the current object.

Returns

true if the specified object is equal to the current object. otherwise, false.

Reimplemented from xtd::object.

equals() [2/2]

bool xtd::threading::cancellation_token::equals ( const cancellation_token & other ) const

overridenoexcept

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

Parameters

other

The object to compare with the current object.

Returns

true if the specified object is equal to the current object. otherwise, false.

get_hash_code()

xtd::size xtd::threading::cancellation_token::get_hash_code ( ) const

overridevirtualnoexcept

Serves as a hash function for a particular type.

Returns

A hash code for the current object.

Reimplemented from xtd::object.

throw_if_cancellation_requested()

void xtd::threading::cancellation_token::throw_if_cancellation_requested

(

)

const

Throws a xtd::operation_canceled_exception if this token has had cancellation requested.

Exceptions

xtd::operation_canceled_exception

The token has had cancellation requested.

Remarks

This method provides functionality equivalent to:

if (tpken.is_cancellation_requested())
  throw xtd::operation_canceled_exception {};

Member Data Documentation

none

cancellation_token xtd::threading::cancellation_token::none

static

Represents an empty xtd::threading::cancellation_token value.

Remarks

The cancellation token returned by this property cannot be canceled; that is, its xtd::cancellation_token::can_be_canceled property is false.

Two empty cancellation tokens are always equal.

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/threading/cancellation_token.hpp