xtd 0.2.0
Loading...
Searching...
No Matches
xtd::threading::event_wait_handle Class Reference
Inheritance diagram for xtd::threading::event_wait_handle:
xtd::threading::wait_handle xtd::icomparable< event_wait_handle > xtd::iequatable< event_wait_handle > xtd::abstract_object xtd::interface xtd::comparison_operators< type_t, comparable_t > xtd::interface xtd::equality_operators< type_t, equatable_t > xtd::object xtd::threading::auto_reset_event xtd::threading::manual_reset_event

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>
Defines a generalized comparison method that a value type or class implements to create a type-specif...
Definition icomparable.h:21
Defines a generalized method that a value type or class implements to create a type-specific method f...
Definition iequatable.h:22
Represents a thread synchronization event.
Definition event_wait_handle.h:37
Encapsulates operating system specific objects that wait for exclusive access to shared resources.
Definition wait_handle.h:52
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.
bool set()
Sets the state of the event to signaled, allowing one or more waiting threads to proceed.
Creates and controls a thread, sets its priority, and gets its status.
Definition thread.h:43
void start()
Causes the operating system to change the state of the current instance to xtd::threading::thread_sta...
virtual bool wait_one()
Blocks the current thread until the current xtd::threading::wait_handle receives a signal.
#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
int64_t int64
Represents a 64-bit signed integer.
Definition int64.h:23
@ i
The I 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
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 string &name)
 Initializes a new instance of the xtd::threading::event_wait_handle class, specifying the name.
 
 event_wait_handle (const string &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 string &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 string &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 string &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 string &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.
 
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.
 

Public Static Methods

static event_wait_handle open_existing (const string &name)
 Opens the specified named synchronization event, if it already exists.
 
static bool try_open_existing (const string &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.
 
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::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
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::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_statetrue 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 string name)
explicit

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

Parameters
nameThe 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 string 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
nameThe 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_newWhen 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 string 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_statetrue to set the initial state to signaled; false to set it to nonsignaled.
nameThe 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 string 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_statetrue to set the initial state to signaled; false to set it to nonsignaled.
nameThe 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_newWhen 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_statetrue to set the initial state to signaled; false to set it to nonsignaled.
modeOne 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_excpetionThe 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 string 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_statetrue to set the initial state to signaled; false to set it to nonsignaled.
modeOne of the xtd::threading::event_reset_mode values that determines whether the event resets automatically or manually.
nameThe 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_excpetionThe mode enum value was out of legal range.
xtd::io::io_exceptionname 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_exceptionThe 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 string 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_statetrue to set the initial state to signaled; false to set it to nonsignaled.
modeOne of the xtd::threading::event_reset_mode values that determines whether the event resets automatically or manually.
nameThe 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_newWhen 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_exceptionname 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_exceptionThe name is too long. Length restrictions may depend on the operating system or configuration.
xtd::threading::wait_handle_cannot_be_opened_exceptionA synchronization object with the provided name cannot be created. A synchronization object of a different type might have the same name.
xtd::argument_exceptionThe 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

◆ 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
valueAn intptr representing the native operating system handle.

Implements xtd::threading::wait_handle.

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

◆ 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_exceptionThe 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_exceptionThe 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.

◆ open_existing()

static event_wait_handle xtd::threading::event_wait_handle::open_existing ( const string name)
static

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

Parameters
nameThe 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_exceptionA 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_exceptionname is an empty string.
xtd::io_io_exceptionname 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_exceptionThe 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.

◆ try_open_existing()

static bool xtd::threading::event_wait_handle::try_open_existing ( const string 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
nameThe 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.
resultWhen 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_exceptionname is an empty string.
xtd::io::io_exceptionname 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_exceptionThe 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.

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

◆ wait()

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

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

Implements xtd::threading::wait_handle.

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

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.

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