xtd 0.2.0
Loading...
Searching...
No Matches
xtd::threading::cancellation_token Class Reference
Inheritance diagram for xtd::threading::cancellation_token:
xtd::object xtd::iequatable< cancellation_token > xtd::interface xtd::equality_operators< type_t, equatable_t >

Definition

Propagates notification that operations should be canceled.

Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.h:42
Propagates notification that operations should be canceled.
Definition cancellation_token.h:39
#define core_export_
Define shared library export.
Definition core_export.h:13
Inheritance
xtd::objectxtd::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_handlewait_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
canceledThe 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_exceptionThe token has had cancellation requested.
Remarks
This method provides functionality equivalent to:
if (tpken.is_cancellation_requested())
The exception that is thrown in a thread upon cancellation of an operation that the thread was execut...
Definition operation_canceled_exception.h:19

◆ 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
objThe 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
static void write_line()
Writes the current line terminator to the standard output stream using the specified format informati...
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10

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_aThe first object to compare.
object_bThe 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
virtual bool equals(const object &obj) const noexcept
Determines whether the specified object is equal to the current object.

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: