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
auto	can_be_canceled () const noexcept -> bool
	Gets whether this token is capable of being in the canceled state.
auto	is_cancellation_requested () const noexcept -> bool
	Gets whether cancellation has been requested for this token.
auto	wait_handle () noexcept -> threading::wait_handle &
	Gets a xtd::threading::wait_handle that is signaled when the token is canceled.

Public Methods
auto	equals (const object &obj) const noexcept -> bool override
	Determines whether the specified object is equal to the current object.
auto	equals (const cancellation_token &other) const noexcept -> bool override
	Determines whether the specified object is equal to the current object.
auto	get_hash_code () const noexcept -> xtd::usize override
	Serves as a hash function for a particular type.
auto	throw_if_cancellation_requested () const -> void
	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 auto	get_type () const noexcept -> type_object
	Gets the type of the current instance.
template<typename object_t>
auto	memberwise_clone () const -> xtd::unique_ptr_object< object_t >
	Creates a shallow copy of the current object.
virtual auto	to_string () const -> xtd::string
	Returns a xtd::string that represents the current object.
virtual auto	equals (const cancellation_token &) const noexcept -> bool=0
	Indicates whether the current object is equal to another object of the same type.
template<typename object_a_t, typename object_b_t>
static auto	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are considered equal.
template<typename object_a_t, typename object_b_t>
static auto	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	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()

auto xtd::threading::cancellation_token::can_be_canceled ( ) const -> bool

nodiscardnoexcept

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()

auto xtd::threading::cancellation_token::is_cancellation_requested ( ) const -> bool

nodiscardnoexcept

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()

auto xtd::threading::cancellation_token::wait_handle ( ) -> threading::wait_handle &

nodiscardnoexcept

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]

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

nodiscardoverridevirtualnoexcept

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]

auto xtd::threading::cancellation_token::equals ( const cancellation_token & other ) const -> bool

nodiscardoverridenoexcept

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()

auto xtd::threading::cancellation_token::get_hash_code ( ) const -> xtd::usize

nodiscardoverridevirtualnoexcept

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()

auto xtd::threading::cancellation_token::throw_if_cancellation_requested

(

)

const -> void

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