xtd::threading::event_wait_handle Class Reference

Inheritance diagram for xtd::threading::event_wait_handle:

Definition

Represents a thread synchronization event.

class event_wait_handle : public xtd::threading::wait_handle, public xtd::icomparable < xtd::threading::event_wait_handle >, public xtd::iequatable<xtd::threading::event_wait_handle>

Header

#include <xtd/threading/event_wait_handle> 

Namespace

xtd::threading

Library

xtd.core

Remarks

The xtd::threading::event_wait_handle class allows threads to communicate with each other by signaling. Typically, one or more threads block on an xtd::threading::event_wait_handle until an unblocked thread calls the xtd::threading::event_wait_handle::set method, releasing one or more of the blocked threads. A thread can signal an xtd::threading::event_wait_handle and then block on it, by calling the static xtd::threading::wait_handle::signal_and_wait method.

Note

The xtd::threading::event_wait_handle class provides access to named system synchronization events.

Remarks

The behavior of an xtd::threading::event_wait_handle that has been signaled depends on its reset mode. An xtd::threading::event_wait_handle created with the xtd::threading::event_reset_mode::auto_reset flag resets automatically when signaled, after releasing a single waiting thread. An xtd::threading::event_wait_handle created with the xtd::threading::event_reset_mode::manual_reset flag remains signaled until its Reset method is called.

Automatic reset events provide exclusive access to a resource. If an automatic reset event is signaled when no threads are waiting, it remains signaled until a thread attempts to wait on it. The event releases the thread and immediately resets, blocking subsequent threads.

Manual reset events are like gates. When the event is not signaled, threads that wait on it will block. When the event is signaled, all waiting threads are released, and the event remains signaled (that is, subsequent waits do not block) until its xtd::threading::event_wait_handle::reset method is called. Manual reset events are useful when one thread must complete an activity before other threads can proceed.

xtd::threading::event_wait_handle objects can be used with the static xtd::threading::wait_handle::wWait_all and xtd::threading::wait_handle::wait_any methods.

Examples

The following code example uses the xtd::threading::wait_handle::signal_and_wait(xtd::threading::wait_handle&, xtd::threading::wait_handle&) method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task.

The example starts five threads and allows them to block on an xtd::threading::event_wait_handle created with the xtd::threading::event_reset_mode::auto_reset flag, then releases one thread each time the user presses the Enter key. The example then queues another five threads and releases them all using an xtd::threading::event_wait_handle created with the xtd::threading::event_reset_mode::manual_reset flag.

#include <xtd/threading/event_wait_handle>
#include <xtd/threading/interlocked>
#include <xtd/threading/thread>
#include <xtd/console>
#include <xtd/startup>
 
using namespace xtd;
using namespace xtd::threading;
 
class example {
private:
  // The event_wait_handle used to demonstrate the difference
  // between auto_reset and manual_reset synchronization events.
  //
  inline static event_wait_handle ewh;
  
  // A counter to make sure all threads are started and
  // blocked before any are released. A Long is used to show
  // the use of the 64-bit Interlocked methods.
  //
  inline static int64 thread_count = 0;
  
  // An auto_reset event that allows the main thread to block
  // until an exiting thread has decremented the count.
  //
  inline static event_wait_handle clear_count {false, event_reset_mode::auto_reset};
  
public:
  static void main() {
    // Create an auto_reset event_wait_handle.
    //
    ewh = event_wait_handle {false, event_reset_mode::auto_reset};
    
    // Create and start five numbered threads. Use the
    // ParameterizedThreadStart delegate, so the thread
    // number can be passed as an argument to the Start
    // method.
    for (auto i = 0; i <= 4; i++) {
      threads_[i] = thread {thread_proc};
      threads_[i].start(i);
    }
    
    // Wait until all the threads have started and blocked.
    // When multiple threads use a 64-bit value on a 32-bit
    // system, you must access the value through the
    // Interlocked class to guarantee thread safety.
    //
    while (interlocked::read(thread_count) < 5) {
      thread::sleep(500);
    }
    
    // Release one thread each time the user presses ENTER,
    // until all threads have been released.
    //
    while (interlocked::read(thread_count) > 0) {
      console::write_line("Press ENTER to release a waiting thread.");
      console::read_line();
      
      // SignalAndWait signals the event_wait_handle, which
      // releases exactly one thread before resetting,
      // because it was created with auto_reset mode.
      // SignalAndWait then blocks on clear_count, to
      // allow the signaled thread to decrement the count
      // before looping again.
      //
      wait_handle::signal_and_wait(ewh, clear_count);
    }
    console::write_line();
    
    // Create a manual_reset event_wait_handle.
    //
    ewh = event_wait_handle(false, event_reset_mode::manual_reset);
    
    // Create and start five more numbered threads.
    //
    for(auto i = 0; i <= 4; i++) {
      threads_[i] = thread {thread_proc};
      threads_[i].start(i);
    }
    
    // Wait until all the threads have started and blocked.
    //
    while (interlocked::read(thread_count) < 5) {
      thread::sleep(500);
    }
    
    // Because the event_wait_handle was created with
    // manual_reset mode, signaling it releases all the
    // waiting threads.
    //
    console::write_line("Press ENTER to release the waiting threads.");
    console::read_line();
    ewh.set();
  }
  
private:
  static void thread_proc(std::any data) {
    console::write_line("Thread {0} blocks.", as<int>(data));
    // Increment the count of blocked threads.
    interlocked::increment(thread_count);
    
    // Wait on the event_wait_handle.
    ewh.wait_one();
    
    console::write_line("Thread {0} exits.", as<int>(data));
    // Decrement the count of blocked threads.
    interlocked::decrement(thread_count);
    
    // After signaling ewh, the main thread blocks on
    // clear_count until the signaled thread has
    // decremented the count. Signal it now.
    //
    clear_count.set();
  }
  
  inline static std::array<thread, 5> threads_;
};
 
startup_(example::main);
 
// This example produces output similar to the following:
//
// Thread 2 blocks.
// Thread 4 blocks.
// Thread 0 blocks.
// Thread 1 blocks.
// Thread 3 blocks.
// Press ENTER to release a waiting thread.
//
// Thread 4 exits.
// Press ENTER to release a waiting thread.
//
// Thread 2 exits.
// Press ENTER to release a waiting thread.
//
// Thread 0 exits.
// Press ENTER to release a waiting thread.
//
// Thread 1 exits.
// Press ENTER to release a waiting thread.
//
// Thread 3 exits.
//
// Thread 0 blocks.
// Thread 1 blocks.
// Thread 3 blocks.
// Thread 2 blocks.
// Thread 4 blocks.
// Press ENTER to release the waiting threads.
//
// Thread 2 exits.
// Thread 1 exits.
// Thread 4 exits.
// Thread 3 exits.
// Thread 0 exits.

Examples

event_wait_handle.cpp.

Public Constructors
	event_wait_handle (bool initial_state)
	Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled.
	event_wait_handle (const ustring &name)
	Initializes a new instance of the xtd::threading::event_wait_handle class, specifying the name.
	event_wait_handle (const ustring &name, bool &created_new)
	Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, the name of a system synchronization event, and a bool variable whose value after the call indicates whether the named system event was created.
	event_wait_handle (bool initial_state, const ustring &name)
	Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled if created as a result of this call, and the name of a system synchronization event.
	event_wait_handle (bool initial_state, const ustring &name, bool &created_new)
	Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled if created as a result of this call, the name of a system synchronization event, and a bool variable whose value after the call indicates whether the named system event was created.
	event_wait_handle (bool initial_state, event_reset_mode mode)
	Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled, and whether it resets automatically or manually.
	event_wait_handle (bool initial_state, event_reset_mode mode, const ustring &name)
	Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, and the name of a system synchronization event.
	event_wait_handle (bool initial_state, event_reset_mode mode, const ustring &name, bool &created_new)
	Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, the name of a system synchronization event, and a bool variable whose value after the call indicates whether the named system event was created.

Public Properties
intptr	handle () const noexcept override
	Gets the native operating system handle.
void	handle (intptr value) override
	Sets the native operating system handle.

Public Methods
void	close () override
	Releases all resources held by the current xtd::threading::wait_handle.
int32	compare_to (const event_wait_handle &value) const noexcept override
bool	equals (const event_wait_handle &value) const noexcept override
bool	reset ()
	Sets the state of the event to nonsignaled, causing threads to block.
bool	set ()
	Sets the state of the event to signaled, allowing one or more waiting threads to proceed.

Public Static Methods
static event_wait_handle	open_existing (const ustring &name)
	Opens the specified named synchronization event, if it already exists.
static bool	try_open_existing (const ustring &name, event_wait_handle &result) noexcept
	Opens the specified named synchronization event, if it already exists, and returns a value that indicates whether the operation succeeded.

Protected Methods
bool	signal () override
	Releases ownership of the specified wait_handle object.
bool	wait (int32 milliseconds_timeout) override
	wait ownership of the specified mutex object.

Additional Inherited Members
Static Public Attributes inherited from xtd::threading::wait_handle
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 Member Functions inherited from xtd::threading::wait_handle
	wait_handle ()=default
	Initializes a new instance of the xtd::threading::wait_handle class.
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 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.
Public Member Functions inherited from xtd::icomparable< event_wait_handle >
virtual int32	compare_to (const event_wait_handle &obj) const noexcept=0
	Compares the current instance with another object of the same type.
Public Member Functions inherited from xtd::iequatable< event_wait_handle >
virtual bool	equals (const event_wait_handle &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type.
Static Public Member Functions inherited from xtd::threading::wait_handle
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.
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::threading::wait_handle
Protected Member Functions inherited from xtd::abstract_object
	abstract_object ()=default
	Initializes a new instance of the xtd::abstract_object class.

Constructor & Destructor Documentation

event_wait_handle() [1/8]

xtd::threading::event_wait_handle::event_wait_handle ( bool  initial_state )

explicit

Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled.

Parameters

initial_state

true to set the initial state to signaled; false to set it to nonsignaled.

Remarks

The mode is set to xtd::threading::event_reset_mode::auto_reset and the name is empty string ("").

event_wait_handle() [2/8]

xtd::threading::event_wait_handle::event_wait_handle ( const ustring &  name )

explicit

Initializes a new instance of the xtd::threading::event_wait_handle class, specifying the name.

Parameters

name

The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

Remarks

The initial state is false and the mode is set to xtd::threading::event_reset_mode::auto_reset.

event_wait_handle() [3/8]

xtd::threading::event_wait_handle::event_wait_handle	(	const ustring &	name,
		bool &	created_new
	)

Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, the name of a system synchronization event, and a bool variable whose value after the call indicates whether the named system event was created.

Parameters

name

The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

created_new

When this method returns, contains true if a local event was created (that is, if name is null or an empty string) or if the specified named system event was created; false if the specified named system event already existed. This parameter is passed uninitialized.

event_wait_handle() [4/8]

xtd::threading::event_wait_handle::event_wait_handle	(	bool	initial_state,
		const ustring &	name
	)

Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled if created as a result of this call, and the name of a system synchronization event.

Parameters

initial_state

true to set the initial state to signaled; false to set it to nonsignaled.

name

The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

event_wait_handle() [5/8]

xtd::threading::event_wait_handle::event_wait_handle	(	bool	initial_state,
		const ustring &	name,
		bool &	created_new
	)

Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled if created as a result of this call, the name of a system synchronization event, and a bool variable whose value after the call indicates whether the named system event was created.

Parameters

initial_state	true to set the initial state to signaled; false to set it to nonsignaled.
name	The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.
created_new	When this method returns, contains true if a local event was created (that is, if name is null or an empty string) or if the specified named system event was created; false if the specified named system event already existed. This parameter is passed uninitialized.

event_wait_handle() [6/8]

xtd::threading::event_wait_handle::event_wait_handle	(	bool	initial_state,
		event_reset_mode	mode
	)

Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled, and whether it resets automatically or manually.

Parameters

initial_state	true to set the initial state to signaled; false to set it to nonsignaled.
mode	One of the xtd::threading::event_reset_mode values that determines whether the event resets automatically or manually.

Remarks

If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the xtd::threading::event_reset_mode::manual_reset flag is specified for mode, threads that wait on the event will not block. If the initial state is signaled, and mode is xtd::threading::event_reset_mode::auto_reset, the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block.

Exceptions

xtd::argument_excpetion

The mode enum value was out of legal range.

event_wait_handle() [7/8]

xtd::threading::event_wait_handle::event_wait_handle	(	bool	initial_state,
		event_reset_mode	mode,
		const ustring &	name
	)

Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, and the name of a system synchronization event.

Parameters

initial_state	true to set the initial state to signaled; false to set it to nonsignaled.
mode	One of the xtd::threading::event_reset_mode values that determines whether the event resets automatically or manually.
name	The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

Exceptions

xtd::argument_excpetion	The mode enum value was out of legal range.
xtd::io::io_exception	name is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\" and "Local" are case-sensitive. -or- There was some other error. The HResult property may provide more information.
xtd::io::path_to_long_exception	The name is too long. Length restrictions may depend on the operating system or configuration.

Remarks

The name may be prefixed with Global\ or Local\ to specify a namespace. When the Global namespace is specified, the synchronization object may be shared with any processes on the system. When the Local namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session.

If a name is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is opened. If a synchronization object of a different type already exists in the namespace, a xtd::threading::wait_handle_cannot_be_opened_exception is thrown. Otherwise, a new synchronization object is created.

If a system event with the name specified for the name parameter already exists, the initialState parameter is ignored.

Warning

When using this constructor for named system events, specify false for initial_state. This constructor provides no way to determine whether a named system event was created, so you cannot make any assumptions about the state of the named event. To determine whether a named event was created, use the xtd::threading::event_wait_handle(bool, xtd::threading::event_reset_mode, xtd::utring, bool) constructor or the xtd::threading::event_wait_handle(bool, xtd::threading::event__reset_mode, xtd:string, bool) constructor.

Remarks

If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the xtd::threading::event_reset_mode::manual_reset flag is specified for mode, threads that wait on the event will not block. If the initial state is signaled, and mode is xtd::threading::event_reset_mode::auto_reset, the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block.

event_wait_handle() [8/8]

xtd::threading::event_wait_handle::event_wait_handle	(	bool	initial_state,
		event_reset_mode	mode,
		const ustring &	name,
		bool &	created_new
	)

Initializes a new instance of the xtd::threading::event_wait_handle class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, the name of a system synchronization event, and a bool variable whose value after the call indicates whether the named system event was created.

Parameters

initial_state	true to set the initial state to signaled; false to set it to nonsignaled.
mode	One of the xtd::threading::event_reset_mode values that determines whether the event resets automatically or manually.
name	The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.
created_new	When this method returns, contains true if a local event was created (that is, if name is null or an empty string) or if the specified named system event was created; false if the specified named system event already existed. This parameter is passed uninitialized.

Exceptions

xtd::io::io_exception	name is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\" and "Local" are case-sensitive. -or- There was some other error. The HResult property may provide more information.
xtd::io::path_too_long_exception	The name is too long. Length restrictions may depend on the operating system or configuration.
xtd::threading::wait_handle_cannot_be_opened_exception	A synchronization object with the provided name cannot be created. A synchronization object of a different type might have the same name.
xtd::argument_exception	The mode enum value was out of legal range.

Remarks

The name may be prefixed with Global\ or Local\ to specify a namespace. When the Global namespace is specified, the synchronization object may be shared with any processes on the system. When the Local namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session

If a name is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is opened. If a synchronization object of a different type already exists in the namespace, a WaitHandleCannotBeOpenedException is thrown. Otherwise, a new synchronization object is created.

If a system event with the name specified for the name parameter already exists, the initialState parameter is ignored. After calling this constructor, use the value in the variable specified for the ref parameter (ByRef parameter in Visual Basic)createdNew to determine whether the named system event already existed or was created.

If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the xtd::threading::event_reset_mode::manual_reset flag is specified for mode, threads that wait on the event will not block. If the initial state is signaled, and mode is xtd::threading::event_reset_mode::auto_reset, the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block.

Member Function Documentation

close()

void xtd::threading::event_wait_handle::close ( )

overridevirtual

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 from xtd::threading::wait_handle.

handle() [1/2]

intptr xtd::threading::event_wait_handle::handle ( ) const

overridevirtualnoexcept

Gets the native operating system handle.

Returns

An intptr representing the native operating system handle.

Implements xtd::threading::wait_handle.

handle() [2/2]

void xtd::threading::event_wait_handle::handle ( intptr  value )

overridevirtual

Sets the native operating system handle.

Parameters

value

An intptr representing the native operating system handle.

Implements xtd::threading::wait_handle.

open_existing()

static event_wait_handle xtd::threading::event_wait_handle::open_existing ( const ustring &  name )

static

Opens the specified named synchronization event, if it already exists.

Parameters

name

The name of the synchronization object to be opened and shared with other processes. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

Returns

An object that represents the named system event.

Exceptions

xtd::threading::wait_handle_cannot_be_opened_exception	A synchronization object with the provided name cannot be opened. It may not exist, or a synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names.
xtd::argument_exception	name is an empty string.
xtd::io_io_exception	name is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\" and "Local" are case-sensitive. -or- There was some other error. The HResult property may provide more information.
xtd::io::path_too_long_exception	The name is too long. Length restrictions may depend on the operating system or configuration.

Remarks

The name may be prefixed with Global\ or Local\ to specify a namespace. When the Global namespace is specified, the synchronization object may be shared with any processes on the system. When the Local namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session.

If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, a xtd::threading::wait_handle_cannot_be_opened_exception is thrown

The xtd::threading::event_wait_handle::open_existing method tries to open the specified named system event. To create the system event when it does not already exist, use one of the xtd::threading::event_wait_handle constructors that has a name parameter.

Multiple calls to this method that use the same value for name do not necessarily return the same xtd::threading::event_wait_handle object, even though the objects that are returned represent the same named system event.

reset()

bool xtd::threading::event_wait_handle::reset

(

)

Sets the state of the event to nonsignaled, causing threads to block.

Returns

true if the operation succeeds; otherwise, false.

Exceptions

xtd::object_closed_exception

The xtd::threading::wait_handle::close() method was previously called on this xtd::threading::event_wait_handle.

set()

bool xtd::threading::event_wait_handle::set

(

)

Sets the state of the event to signaled, allowing one or more waiting threads to proceed.

Returns

true if the operation succeeds; otherwise, false.

Exceptions

xtd::object_closed_exception

The xtd::threading::wait_handle::close() method was previously called on this xtd::threading::event_wait_handle.

Remarks

For an xtd::threading::event_wait_handle with xtd::threading::event_reset_mode::auto_reset (including xtd::threading:::auto_reset_event), the xtd::threading::event_wait_handle::set method releases a single thread. If there are no waiting threads, the wait handle remains signaled until a thread attempts to wait on it, or until its xtd::threading::event_wait_handle::reset method is called.

Warning

There is no guarantee that every call to the xtd::threading::auto_reset_event::set method will release a thread. If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It's as if the second call did not happen. Also, if xtd::threading::auto_reset_event::set is called when there are no threads waiting and the xtd::threading::auto_reset_event is already signaled, the call has no effect.

Remarks

For an xtd::threading::event_wait_handle with xtd::threading::event_reset_mode::manual_reset (including xtd::threading:::manual_reset_event), calling the Set method leaves the wait handle in a signaled state until its xtd::threading::event_wait_handle::reset method is called.

Examples

event_wait_handle.cpp.

signal()

bool xtd::threading::event_wait_handle::signal ( )

overrideprotectedvirtual

Releases ownership of the specified wait_handle object.

Returns

true If the function succeeds, false otherwise.

Remarks

Override this function for all derived object

Implements xtd::threading::wait_handle.

try_open_existing()

static bool xtd::threading::event_wait_handle::try_open_existing ( const ustring &  name, event_wait_handle &  result  )

staticnoexcept

Opens the specified named synchronization event, if it already exists, and returns a value that indicates whether the operation succeeded.

Parameters

name

The name of the synchronization object to be opened and shared with other processes. The name is case-sensitive. The backslash character () is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

result

When this method returns, contains a The xtd::threading::event_wait_handle object that represents the named synchronization event if the call succeeded, or null if the call failed. This parameter is treated as uninitialized.

Returns

true if the named synchronization event was opened successfully; otherwise, false. In some cases, false may be returned for invalid names.

Exceptions

xtd::argument_exception	name is an empty string.
xtd::io::io_exception	name is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\" and "Local" are case-sensitive. For some invalid names, the method may return false instead. -or- There was some other error. The HResult property may provide more information.
xtd::io::path_too_long_exception	The name is too long. Length restrictions may depend on the operating system or configuration.

Remarks

The name may be prefixed with Global\ or Local\ to specify a namespace. When the Global namespace is specified, the synchronization object may be shared with any processes on the system. When the Local namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session.

If a synchronization object of the requested type exists in the namespace, the existing synchronization object is opened. If a synchronization object does not exist in the namespace, or a synchronization object of a different type exists in the namespace, false is returned.

To create the system event when it does not already exist, use one of the xtd::threading::event_wait_handle constructors that has a name parameter.

If you are uncertain whether a named synchronization event exists, use this method overload instead of the xtd::threading::event_xait_handle::open_existing(xtd::uttring) method overload, which throws an exception if the synchronization event does not exist.

Multiple calls to this method that use the same value for name do not necessarily return the same xtd::threading::event_wait_handle object, even though the objects that are returned represent the same named system event.

wait()

bool xtd::threading::event_wait_handle::wait ( int32  milliseconds_timeout )

overrideprotectedvirtual

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

Implements xtd::threading::wait_handle.

---

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

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