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>(std::vector<xtd::threading::tasks::task<antecedent_result_t>>, xtd::func<std::vector<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 cancellation_token &other) const noexcept
void	throw_if_cancellation_requested () const
	Throws a xtd::operation_canceled_exception if this token has had cancellation requested.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
template<typename object_a_t , typename 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.

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<typename object_t >
xtd::uptr< 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.
Public Member Functions inherited from xtd::iequatable< cancellation_token >
virtual bool	equals (const cancellation_token &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type.
Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename 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<typename object_a_t , typename 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.

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 {};

equals() [1/2]

virtual bool xtd::object::equals ( const object &  obj ) const

virtualnoexcept

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.

Examples

The following code example compares the current instance with another object.

#include <xtd/console>
 
using namespace xtd;
 
auto main() -> int {
  auto object1 = new_ptr<object>();
  auto object2 = new_ptr<object>();
  
  auto object3 = object2;
  console::write_line(object1->equals(*object3));
  console::write_line(*object1 == *object3);
  object3 = object1;
  console::write_line(object1->equals(*object3));
  console::write_line(*object1 == *object3);
}
 
// This code produces the following output :
//
// false
// false
// true
// true

Reimplemented from xtd::object.

equals() [2/2]

template<typename object_a_t , typename object_b_t >

static bool xtd::object::equals ( const object_a_t &  object_a, const object_b_t &  object_b  )

inlinestaticnoexcept

Determines whether the specified object instances are considered equal.

Parameters

object_a	The first object to compare.
object_b	The second object to compare.

Returns

true if object_a is the same instance as object_b or if both are null references or if object_a(object_b) returns true. otherwise, false.

Examples

The following code example compares different objects.

#include <xtd/console>
 
using namespace xtd;
 
auto main() -> int {
  string s1 = "Tom";
  string s2 = "Carol";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "Tom";
  s2 = "Tom";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "";
  s2 = "Tom";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "Carol";
  s2 = "";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "";
  s2 = "";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
}
 
// This code produces the following output :
//
// object::equals("Tom", "Carol") => false
// object::equals("Tom", "Tom") => true
// object::equals("", "Tom") => false
// object::equals("Carol", "") => false
// object::equals("", "") => true

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.h