xtd::threading::wait_handle Class Reference

Inheritance diagram for xtd::threading::wait_handle:

Definition

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

class core_export_ wait_handle abstract_

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:

• The xtd::threading::mutex class.
• The xtd::threading::event_wait_handle class and its derived classes, xtd::threading::auto_reset_event and xtd::threading::manual_reset_event.
• The xtd::threading::semaphore class.

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:

• xtd::threading::wait_handle::signal_and_wait, which allows a thread to signal one wait handle and immediately wait on another.
• xtd::threading::wait_handle::wait_all, which allows a thread to wait until all the wait handles in an array receive a signal.
• xtd::threading::wait_handle::wait_any, which allows a thread to wait until any one of a specified set of wait handles has been signaled.

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

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.
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 >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object.
virtual xtd::ustring	to_string () const noexcept
	Returns a sxd::ustring that represents the current object.
Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal.
static bool	reference_equals (const object &object_a, const object &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

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.

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

value

An intptr representing the native operating system handle.

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

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.

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_signal	The xtd::threading::wait_handle to signal.
to_wait	The 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_exception	the to_signal and/or to_wait are invalid
xtd::invalid_operation_exception	to_signal is a semaphore, and it already has a full count.
xtd::threading::abandoned_mutex_exception	The 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, 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_signal	The wait_handle to signal.
to_wait	The wait_handle to wait on.
timeout	A 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_exception	the to_signal and/or to_wait are invalid
xtd::invalid_operation_exception	to_signal is a semaphore, and it already has a full count.
xtd::threading::abandoned_mutex_exception	The 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, 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_signal	The xtd::threading::wait_handle to signal.
to_wait	The xtd::threading::wait_handle to wait on.
milliseconds_timeout	An 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_exception	the to_signal and/or to_wait are invalid
xtd::invalid_operation_exception	to_signal is a semaphore, and it already has a full count.
xtd::threading::abandoned_mutex_exception	The wait completed because a thread exited without releasing a mutex.

wait()

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

protectedpure virtual

wait ownership of the specified mutex object.

Parameters

handle	A valid handle to an open object.
milliseconds_timeout	The 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.

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_handles

A 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_exception	the to_signal and/or to_wait are invalid
xtd::argument_exception	The number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exception	The 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, 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_handles	A 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.
timeout	A 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_exception	timeout 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_exception	the to_signal and/or to_wait are invalid
xtd::argument_exception	The number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exception	The 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, 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_handles	A 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_timeout	The 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_exception	timeout 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_exception	the to_signal and/or to_wait are invalid
xtd::argument_exception	The number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exception	The 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_handles

A 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_exception	timeout 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_exception	the to_signal and/or to_wait are invalid
xtd::argument_exception	The number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exception	The 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, 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_handles	A 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.
timeout	A 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_exception	timeout 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_exception	the to_signal and/or to_wait are invalid
xtd::argument_exception	The number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exception	The 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, 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_handles	A 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_timeout	The 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_exception	timeout 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_exception	the to_signal and/or to_wait are invalid
xtd::argument_exception	The number of objects in wait_handles is greater than the system permits.
xtd::threading::abandoned_mutex_exception	The wait completed because a thread exited without releasing a mutex.

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_exception	the handle is invalid
xtd::threading::abandoned_mutex_exception	The 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 ( 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

timeout

A 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_exception	the handle is invalid
xtd::threading::abandoned_mutex_exception	The wait completed because a thread exited without releasing a mutex.
xtd::argument_exception	milliseconds_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 ( 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_timeout

The 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_exception	the handle is invalid
xtd::threading::abandoned_mutex_exception	The wait completed because a thread exited without releasing a mutex.
xtd::argument_exception	milliseconds_timeout is a negative number other than -1, which represents an infinite time-out.

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:

• xtd.core/include/xtd/threading/wait_handle.h