xtd 0.2.0
Loading...
Searching...
No Matches
xtd::threading::wait_handle Class Referenceabstract
Inheritance diagram for xtd::threading::wait_handle:
xtd::abstract_object xtd::object xtd::threading::event_wait_handle xtd::threading::mutex xtd::threading::semaphore xtd::threading::auto_reset_event xtd::threading::manual_reset_event

Definition

Encapsulates operating system specific objects that wait for exclusive access to shared resources.

Encapsulates operating system specific objects that wait for exclusive access to shared resources.
Definition wait_handle.h:52
#define abstract_
This keyword is used to represents an abstract class.
Definition abstract.h:25
#define core_export_
Define shared library export.
Definition core_export.h:13
Header
#include <xtd/threading/wait_handle>
Namespace
xtd::threading
Library
xtd.core
Remarks
The xtd::threading::wait_handle class encapsulates a native operating system synchronization handle and is used to represent all synchronization objects in the runtime that allow multiple wait operations.
The xtd::threading::wait_handle class itself is abstract. Classes derived from xtd::threading::wait_handle define a signaling mechanism to indicate taking or releasing access to a shared resource, but they use the inherited xtd::threading::wait_handle methods to block while waiting for access to shared resources. The classes derived from xtd::threading::wait_handle include:
Threads can block on an individual wait handle by calling the instance method xtd::threading::wait_handle::wait_one, which is inherited by classes derived from xtd::threading::wait_handle.
The derived classes of xtd::threading::wait_handle differ in their thread affinity. Event wait handles (xtd::threading::envent_wait_handle, xtd::threading::auto_reset_event, and xtd::threading::manual_reset_event) and semaphores do not have thread affinity; any thread can signal an event wait handle or semaphore. Mutexes, on the other hand, do have thread affinity; the thread that owns a mutex must release it, and an exception is thrown if a thread calls the xtd::threading::mutex::release_mutex method on a mutex that it does not own.
In addition to its derived classes, the xtd::threading::wait_handle class has a number of static methods that block a thread until one or more synchronization objects receive a signal. These include:
The overloads of these methods provide timeout intervals for abandoning the wait, and the opportunity to exit a synchronization context before entering the wait, allowing other threads to use the synchronization context.
Examples
The following code example shows how two threads can do background tasks while the Main thread waits for the tasks to complete using the static xtd::threading::wait_handle::wait_any and xtd::threading::wait_handle::wait_all methods of the xtd::threading::wait_handle class.
#include <xtd/threading/auto_reset_event>
#include <xtd/threading/thread_pool>
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/random>
#include <xtd/startup>
using namespace xtd;
using namespace xtd::threading;
namespace wait_handle_example {
class program {
public:
static void main() {
// Queue up two tasks on two different threads;
// wait until all tasks are completed.
auto dt = date_time::now();
console::write_line("Main thread is waiting for BOTH tasks to complete.");
thread_pool::queue_user_work_item(do_task, event1);
thread_pool::queue_user_work_item(do_task, event2);
wait_handle::wait_all({event1, event2});
// The time shown below should match the longest task.
console::write_line("Both tasks are completed (time waited={0})",
date_time::now() - dt);
// Queue up two tasks on two different threads;
// wait until any task is completed.
dt = date_time::now();
console::write_line();
console::write_line("The main thread is waiting for either task to complete.");
thread_pool::queue_user_work_item(do_task, event1);
thread_pool::queue_user_work_item(do_task, event2);
auto index = wait_handle::wait_any({event1, event2});
// The time shown below should match the shortest task.
console::write_line("Task {0} finished first (time waited={1}).",
index + 1, date_time::now() - dt);
}
static void do_task(std::any state) {
auto are = as<auto_reset_event>(state);
auto time = 1000 * r.next(2, 10);
console::write_line("Performing a task for {0} milliseconds.", time);
thread::sleep(time);
are.set();
}
private:
// Define two auto_reset_event.
inline static auto_reset_event event1 {false};
inline static auto_reset_event event2 {false};
// Define a random number generator for testing.
inline static xtd::random r;
};
}
startup_(wait_handle_example::program::main);
// This example produces output similar to the following:
//
// Main thread is waiting for BOTH tasks to complete.
// Performing a task for 4000 milliseconds.
// Performing a task for 9000 milliseconds.
// Both tasks are completed (time waited=00:00:09:011011000)
//
// The main thread is waiting for either task to complete.
// Performing a task for 7000 milliseconds.
// Performing a task for 4000 milliseconds.
// Task 2 finished first (time waited=00:00:04:011925000).
Represents a pseudo-random number generator, a device that produces a sequence of numbers that meet c...
Definition random.h:40
Represents a thread synchronization event that, when signaled, resets automatically after releasing a...
Definition auto_reset_event.h:36
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.h:175
@ r
The R key.
The xtd::threading namespace provides classes and interfaces that enable multithreaded programming....
Definition abandoned_mutex_exception.h:11
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10

Public Fields

static const intptr invalid_handle
 Represents an invalid native operating system handle. This field is read-only.
 
static constexpr size_t wait_timeout
 Indicates that a xtd::threading::wait_handle::wait_any operation timed out before any of the wait handles were signaled. This field is constant.
 

Public Constructors

 wait_handle ()=default
 Initializes a new instance of the xtd::threading::wait_handle class.
 

Public Properties

virtual intptr handle () const noexcept=0
 Gets the native operating system handle.
 
virtual void handle (intptr value)=0
 Sets the native operating system handle.
 

Public Methods

virtual void close ()
 Releases all resources held by the current xtd::threading::wait_handle.
 
virtual bool wait_one ()
 Blocks the current thread until the current xtd::threading::wait_handle receives a signal.
 
virtual bool wait_one (int32 milliseconds_timeout)
 Blocks the current thread until the current xtd::threading::wait_handle receives a signal, using 32-bit signed integer to measure the time interval.
 
virtual bool wait_one (const time_span &timeout)
 Blocks the current thread until the current instance receives a signal, using a xtd::time_span to measure the time interval.
 

Public Static Methods

static bool signal_and_wait (wait_handle &to_signal, wait_handle &to_wait)
 Signals one xtd::threading::wait_handle and waits on another.
 
static bool signal_and_wait (wait_handle &to_signal, wait_handle &to_wait, int32 milliseconds_timeout)
 Signals one xtd::threading::wait_handle and waits on another, specifying a time-out interval as a 32-bit signed integer.
 
static bool signal_and_wait (wait_handle &to_signal, wait_handle &to_wait, const time_span &timeout)
 Signals one xtd::threading::wait_handle and waits on another, specifying a time-out interval as a time_span.
 
template<typename collection_t >
static bool wait_all (const collection_t &wait_handles)
 Waits for all the elements in the specified collection to receive a signal.
 
template<typename collection_t >
static bool wait_all (const collection_t &wait_handles, int32 milliseconds_timeout)
 Waits for all the elements in the specified collection to receive a signal, using an int32 value to measure the time interval.
 
template<typename collection_t >
static bool wait_all (const collection_t &wait_handles, const time_span &timeout)
 Waits for all the elements in the specified collection to receive a signal, using a xtd::time_span value to measure the time interval.
 
template<typename collection_t >
static size_t wait_any (const collection_t &wait_handles)
 Waits for any of the elements in the specified collection to receive a signal.
 
template<typename collection_t >
static size_t wait_any (const collection_t &wait_handles, int32 milliseconds_timeout)
 Waits for any of the elements in the specified collection to receive a signal, using a 32-bit signed integer to measure the time interval.
 
template<typename collection_t >
static size_t wait_any (const collection_t &wait_handles, const time_span &timeout)
 Waits for any of the elements in the specified collection to receive a signal, using a xtd::time_span to measure the time interval.
 

Protected Methods

virtual bool signal ()=0
 Releases ownership of the specified wait_handle object.
 
virtual bool wait (int32 milliseconds_timeout)=0
 wait ownership of the specified mutex object.
 

Additional Inherited Members

- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object.
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current 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.
 
- 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.
 
- Protected Member Functions inherited from xtd::abstract_object
 abstract_object ()=default
 Initializes a new instance of the xtd::abstract_object class.
 

Constructor & Destructor Documentation

◆ wait_handle()

xtd::threading::wait_handle::wait_handle ( )
default

Initializes a new instance of the xtd::threading::wait_handle class.

Member Function Documentation

◆ handle() [1/2]

virtual intptr xtd::threading::wait_handle::handle ( ) const
pure virtualnoexcept

Gets the native operating system handle.

Returns
An intptr representing the native operating system handle.

Implemented in xtd::threading::event_wait_handle, xtd::threading::mutex, and xtd::threading::semaphore.

◆ handle() [2/2]

virtual void xtd::threading::wait_handle::handle ( intptr  value)
pure virtual

Sets the native operating system handle.

Parameters
valueAn intptr representing the native operating system handle.

Implemented in xtd::threading::event_wait_handle, xtd::threading::mutex, and xtd::threading::semaphore.

◆ close()

virtual void xtd::threading::wait_handle::close ( )
virtual

Releases all resources held by the current xtd::threading::wait_handle.

Remarks
You to call this method in the destructor of the inherited class.

Reimplemented in xtd::threading::event_wait_handle, xtd::threading::mutex, and xtd::threading::semaphore.

◆ wait_one() [1/3]

virtual bool xtd::threading::wait_handle::wait_one ( )
virtual

Blocks the current thread until the current xtd::threading::wait_handle receives a signal.

Returns
true if the current instance receives a signal. If the current instance is never signaled, xtd::threading::wait_handle.wait_one(int32, bool) never returns.
Exceptions
xtd::object_closed_exceptionthe handle is invalid
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.
Examples
event_wait_handle.cpp, and monitor_lock.cpp.

◆ wait_one() [2/3]

virtual bool xtd::threading::wait_handle::wait_one ( int32  milliseconds_timeout)
virtual

Blocks the current thread until the current xtd::threading::wait_handle receives a signal, using 32-bit signed integer to measure the time interval.

Parameters
milliseconds_timeoutThe number of milliseconds to wait, or xtd::threading::timeout::infinite (-1) to wait indefinitely.
Returns
if the current instance receives a signal. If the current instance is never signaled, xtd::threading::wait_handle.wait_one(int32, bool) never returns.
Exceptions
xtd::object_closed_exceptionthe handle is invalid
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.
xtd::argument_exceptionmilliseconds_timeout is a negative number other than -1, which represents an infinite time-out.

◆ wait_one() [3/3]

virtual bool xtd::threading::wait_handle::wait_one ( const time_span timeout)
virtual

Blocks the current thread until the current instance receives a signal, using a xtd::time_span to measure the time interval.

Parameters
timeoutA xtd::time_span that represents the number of milliseconds to wait, or a xtd::time_span that represents -1 milliseconds to wait indefinitely.
Returns
true if the current instance receives a signal. If the current instance is never signaled, xtd::threading::wait_handle.wait_one(int32, bool) never returns.
Exceptions
xtd::object_closed_exceptionthe handle is invalid
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.
xtd::argument_exceptionmilliseconds_timeout is a negative number other than -1, which represents an infinite time-out.

◆ signal_and_wait() [1/3]

static bool xtd::threading::wait_handle::signal_and_wait ( wait_handle to_signal,
wait_handle to_wait 
)
static

Signals one xtd::threading::wait_handle and waits on another.

Parameters
to_signalThe xtd::threading::wait_handle to signal.
to_waitThe xtd::threading::wait_handle to wait on.
Returns
bool true if both the signal and the wait complete successfully; if the wait does not complete, the method does not return.
Exceptions
xtd::object_closed_exceptionthe to_signal and/or to_wait are invalid
xtd::invalid_operation_exceptionto_signal is a semaphore, and it already has a full count.
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.

◆ signal_and_wait() [2/3]

static bool xtd::threading::wait_handle::signal_and_wait ( wait_handle to_signal,
wait_handle to_wait,
int32  milliseconds_timeout 
)
static

Signals one xtd::threading::wait_handle and waits on another, specifying a time-out interval as a 32-bit signed integer.

Parameters
to_signalThe xtd::threading::wait_handle to signal.
to_waitThe xtd::threading::wait_handle to wait on.
milliseconds_timeoutAn integer that represents the interval to wait. If the value is xtd::threading::timeout::infinite, that is, -1, the wait is infinite
Returns
bool true if both the signal and the wait complete successfully; if the wait does not complete, the method does not return.
Exceptions
xtd::object_closed_exceptionthe to_signal and/or to_wait are invalid
xtd::invalid_operation_exceptionto_signal is a semaphore, and it already has a full count.
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.

◆ signal_and_wait() [3/3]

static bool xtd::threading::wait_handle::signal_and_wait ( wait_handle to_signal,
wait_handle to_wait,
const time_span timeout 
)
static

Signals one xtd::threading::wait_handle and waits on another, specifying a time-out interval as a time_span.

Parameters
to_signalThe wait_handle to signal.
to_waitThe wait_handle to wait on.
timeoutA time_span that represents the interval to wait. If the value is -1, the wait is infinite
Returns
bool true if both the signal and the wait complete successfully; if the wait does not complete, the method does not return.
Exceptions
xtd::object_closed_exceptionthe to_signal and/or to_wait are invalid
xtd::invalid_operation_exceptionto_signal is a semaphore, and it already has a full count.
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.

◆ wait_all() [1/3]

template<typename collection_t >
static bool xtd::threading::wait_handle::wait_all ( const collection_t &  wait_handles)
inlinestatic

Waits for all the elements in the specified collection to receive a signal.

Parameters
wait_handlesA xtd::threading::wait_handle collection containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object.
Returns
true when every element in wait_handles has received a signal; otherwise the method never returns.
Exceptions
xtd::object_closed_exceptionthe to_signal and/or to_wait are invalid
xtd::argument_exceptionThe number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.

◆ wait_all() [2/3]

template<typename collection_t >
static bool xtd::threading::wait_handle::wait_all ( const collection_t &  wait_handles,
int32  milliseconds_timeout 
)
inlinestatic

Waits for all the elements in the specified collection to receive a signal, using an int32 value to measure the time interval.

Parameters
wait_handlesA xtd::threading::wait_handle collection containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object.
milliseconds_timeoutThe number of milliseconds to wait, or xtd::threading::timeout::infinite (-1) to wait indefinitely.
Returns
true when every element in wait_handles has received a signal; otherwise the method never returns.
Exceptions
xtd::argument_exceptiontimeout is a negative number other than -1 milliseconds, which represents an infinite time-out.
-or-
The number of objects in wait_handles is greater than the system permits.
xtd::object_closed_exceptionthe to_signal and/or to_wait are invalid
xtd::argument_exceptionThe number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.

◆ wait_all() [3/3]

template<typename collection_t >
static bool xtd::threading::wait_handle::wait_all ( const collection_t &  wait_handles,
const time_span timeout 
)
inlinestatic

Waits for all the elements in the specified collection to receive a signal, using a xtd::time_span value to measure the time interval.

Parameters
wait_handlesA xtd::threading::wait_handle collection containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object.
timeoutA xtd::time_span that represents the number of milliseconds to wait, or a xtd::time_span that represents -1 milliseconds, to wait indefinitely.
Returns
true when every element in wait_handles has received a signal; otherwise the method never returns.
Exceptions
xtd::argument_exceptiontimeout is a negative number other than -1 milliseconds, which represents an infinite time-out.
-or-
The number of objects in wait_handles is greater than the system permits.
xtd::object_closed_exceptionthe to_signal and/or to_wait are invalid
xtd::argument_exceptionThe number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.

◆ wait_any() [1/3]

template<typename collection_t >
static size_t xtd::threading::wait_handle::wait_any ( const collection_t &  wait_handles)
inlinestatic

Waits for any of the elements in the specified collection to receive a signal.

Parameters
wait_handlesA xtd::threading::wait_handle collection containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object.
Returns
The array index of the object that satisfied the wait.
Exceptions
xtd::argument_exceptiontimeout is a negative number other than -1 milliseconds, which represents an infinite time-out.
-or-
The number of objects in wait_handles is greater than the system permits.
xtd::object_closed_exceptionthe to_signal and/or to_wait are invalid
xtd::argument_exceptionThe number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.

◆ wait_any() [2/3]

template<typename collection_t >
static size_t xtd::threading::wait_handle::wait_any ( const collection_t &  wait_handles,
int32  milliseconds_timeout 
)
inlinestatic

Waits for any of the elements in the specified collection to receive a signal, using a 32-bit signed integer to measure the time interval.

Parameters
wait_handlesA xtd::threading::wait_handle collection containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object.
milliseconds_timeoutThe number of milliseconds to wait, or xtd::threading::timeout::infinite (-1) to wait indefinitely.
Returns
The array index of the object that satisfied the wait, or xtd::threading::wait_handle::wait_timeout if no object satisfied the wait and a time interval equivalent to milliseconds_timeout has passed.
Exceptions
xtd::argument_exceptiontimeout is a negative number other than -1 milliseconds, which represents an infinite time-out.
-or-
The number of objects in wait_handles is greater than the system permits.
xtd::object_closed_exceptionthe to_signal and/or to_wait are invalid
xtd::argument_exceptionThe number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.

◆ wait_any() [3/3]

template<typename collection_t >
static size_t xtd::threading::wait_handle::wait_any ( const collection_t &  wait_handles,
const time_span timeout 
)
inlinestatic

Waits for any of the elements in the specified collection to receive a signal, using a xtd::time_span to measure the time interval.

Parameters
wait_handlesA xtd::threading::wait_handle collection containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object.
timeoutA xtd::time_span that represents the number of milliseconds to wait, or a xtd::time_span that represents -1 milliseconds to wait indefinitely.
Returns
The array index of the object that satisfied the wait, or xtd::threading::wait_handle::wait_timeout if no object satisfied the wait and a time interval equivalent to timeout has passed.
Exceptions
xtd::argument_exceptiontimeout is a negative number other than -1 milliseconds, which represents an infinite time-out.
-or-
The number of objects in wait_handles is greater than the system permits.
xtd::object_closed_exceptionthe to_signal and/or to_wait are invalid
xtd::argument_exceptionThe number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exceptionThe wait completed because a thread exited without releasing a mutex.

◆ signal()

virtual bool xtd::threading::wait_handle::signal ( )
protectedpure virtual

Releases ownership of the specified wait_handle object.

Returns
true If the function succeeds, false otherwise.
Remarks
Override this function for all derived object

Implemented in xtd::threading::event_wait_handle, xtd::threading::mutex, and xtd::threading::semaphore.

◆ wait()

virtual bool xtd::threading::wait_handle::wait ( int32  milliseconds_timeout)
protectedpure virtual

wait ownership of the specified mutex object.

Parameters
handleA valid handle to an open object.
milliseconds_timeoutThe number of milliseconds to wait, or -1 to wait indefinitely.
Returns
true if the current instance receives a signal; otherwise, false.
Remarks
If milliseconds_timeout is zero, the method does not block. It tests the state of the wait handle and returns immediately.
Override this function for all derived object

Implemented in xtd::threading::event_wait_handle, xtd::threading::mutex, and xtd::threading::semaphore.

Member Data Documentation

◆ invalid_handle

const intptr xtd::threading::wait_handle::invalid_handle
static

Represents an invalid native operating system handle. This field is read-only.

Remarks
Used internally to initialize the xtd::threading::wait_handle::handle property.
Notes to Inheritors
You can use this value to determine whether the xtd::threading::wait_handle::handle property contains a valid native operating system handle.

◆ wait_timeout

constexpr size_t xtd::threading::wait_handle::wait_timeout
staticconstexpr

Indicates that a xtd::threading::wait_handle::wait_any operation timed out before any of the wait handles were signaled. This field is constant.

Remarks
This field is one of the possible return values of xtd::threading::wait_handle::wait_any.

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