|
xtd
0.2.0
|
Definition
Represents a thread synchronization event that, when signaled, must be reset manually. This class cannot be inherited.
- Header
- #include <xtd/threading/manual_reset_event>
- Namespace
- xtd::threading
- Library
- xtd.core
- Remarks
- You use xtd::threading::auto_reset_event, xtd::threading::manual_reset_event, and xtd::threading::event_wait_handle for thread interaction (or thread signaling).
- When a thread begins an activity that must complete before other threads proceed, it calls xtd::threading::event_wait_handle::reset to put xtd::threading::manual_reset_event in the non-signaled state. This thread can be thought of as controlling the xtd::threading::manual_reset_event. Threads that call xtd::threading::wait_handle::wait_one block, awaiting the signal. When the controlling thread completes the activity, it calls xtd::threading::event_wait_handle::set to signal that the waiting threads can proceed. All waiting threads are released.
- Once it has been signaled, xtd::threading::manual_reset_event remains signaled until it is manually reset by calling the xtd::threading::event_wait_handle::reset() method. That is, calls to xtd::threading::wait_handle:wait_one return immediately.
- You can control the initial state of a xtd::threading::manual_reset_event by passing a bool value to the constructor: true if the initial state is signaled, and false otherwise.
- xtd::threading::manual_reset_event can also be used with the static xtd::threading::wait_handle::wait_all and xtd::threading::wait_handle::wait_any methods.
- Warning
- Unlike the xtd::threading::manual_reset_event class, the xtd::threading::event_wait_handle class provides access to named system synchronization events.
- example
- The following example demonstrates how xtd::threading::manual_reset_event works. The example starts with a xtd::threading::manual_reset_event in the unsignaled state (that is, false is passed to the constructor). The example creates three threads, each of which blocks on the xtd::threading::manual_reset_event by calling its wtd::threading::wait_handle::wait_one method. When the user presses the Enter key, the example calls the wtd::threading::event_wait_handle::set method, which releases all three threads. Contrast this with the behavior of the wtd::threading::auto_reset_event class, which releases threads one at a time, resetting automatically after each release.
Pressing the Enter key again demonstrates that the xtd::threading::manual_reset_event remains in the signaled state until its wtd::threading::event_wait_handle::reset method is called: The example starts two more threads. These threads do not block when they call the wtd::threading::wait_handle::wait_one method, but instead run to completion.
Pressing the Enter key again causes the example to call the wtd::threading::event_wait_handle::reset method and to start one more thread, which blocks when it calls wtd::threading::wait_handle::wait_one. Pressing the Enter key one final time calls wtd::threading::event_wait_handle::set to release the last thread, and the program ends.#include <xtd/threading/manual_reset_event>#include <xtd/threading/thread>#include <xtd/console>#include <xtd/startup>using namespace xtd;using namespace xtd::threading;namespace manual_reset_event_example {class program {public:static void main() {console::write_line("\nStart 3 named threads that block on a ManualresetEvent:\n");threads.emplace_back(thread_proc);threads.back().name(ustring::format("Thread_{}", i));threads.back().start();}thread::sleep(500);console::write_line("\nWhen all three threads have started, press Enter to call set()""\nto release all the threads.\n");mre.set();thread::sleep(500);console::write_line("\nWhen a ManualresetEvent is signaled, threads that call WaitOne()""\ndo not block. Press Enter to show this.\n");threads.emplace_back(thread_proc);threads.back().name(ustring::format("Thread_{}", i));threads.back().start();}thread::sleep(500);console::write_line("\nPress Enter to call reset(), so that threads once again block""\nwhen they call WaitOne().\n");mre.reset();// Start a thread that waits on the ManualresetEvent.threads.emplace_back(thread_proc);threads.back().name("Thread_5");threads.back().start();thread::sleep(500);console::write_line("\nPress Enter to call set() and conclude the demo.");mre.set();thread::join_all(threads);}private:inline static std::vector<thread> threads = std::vector<thread>(4);// mre is used to block and release threads manually. It is// created in the unsignaled state.static void thread_proc() {console::write_line(name + " starts and calls mre.WaitOne()");mre.wait_one();console::write_line(name + " ends.");}};}startup_(manual_reset_event_example::program::main);// This example produces output similar to the following://// Start 3 named threads that block on a ManualresetEvent://// Thread_0 starts and calls mre.WaitOne()// Thread_2 starts and calls mre.WaitOne()// Thread_1 starts and calls mre.WaitOne()//// When all three threads have started, press Enter to call set()// to release all the threads.////// Thread_2 ends.// Thread_0 ends.// Thread_1 ends.//// When a ManualresetEvent is signaled, threads that call WaitOne()// do not block. Press Enter to show this.////// Thread_3 starts and calls mre.WaitOne()// Thread_4 starts and calls mre.WaitOne()// Thread_3 ends.// Thread_4 ends.//// Press Enter to call reset(), so that threads once again block// when they call WaitOne().////// Thread_5 starts and calls mre.WaitOne()//// Press Enter to call set() and conclude the demo.//// Thread_5 ends.
- Examples:
- manual_reset_event.cpp.
Constructors | |
| manual_reset_event ()=default | |
| manual_reset_event (bool initial_state) | |
| Initializes a new instance of the xtd::threading::manual_reset_event class with a bool value indicating whether to set the initial state to signaled. More... | |
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. More... | |
| static constexpr size_t | wait_timeout = std::numeric_limits<size_t>::max() |
| Indicates that a xtd::threading::wait_handle::wait_any operation timed out before any of the wait handles were signaled. This field is constant. This field is one of the possible return values of xtd::threading::wait_handle::wait_any. More... | |
| Public Member Functions inherited from xtd::threading::event_wait_handle | |
| event_wait_handle () | |
| 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. More... | |
| event_wait_handle (const ustring &name) | |
| Initializes a new instance of the xtd::threading::event_wait_handle class, specifying the name. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| intptr | handle () const noexcept override |
| Gets the native operating system handle. More... | |
| void | handle (intptr value) override |
| Sets the native operating system handle. More... | |
| void | close () override |
| Releases all resources held by the current xtd::threading::wait_handle. More... | |
| 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. More... | |
| bool | set () |
| Sets the state of the event to signaled, allowing one or more waiting threads to proceed. More... | |
| Public Member Functions inherited from xtd::threading::wait_handle | |
| wait_handle ()=default | |
| Initializes a new instance of the xtd::threading::wait_handle class. More... | |
| virtual bool | wait_one () |
| Blocks the current thread until the current xtd::threading::wait_handle receives a signal. More... | |
| 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. More... | |
| 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. More... | |
| Public Member Functions inherited from xtd::object | |
| object ()=default | |
| Create a new instance of the ultimate base class object. More... | |
| bool | equals (const object &obj) const noexcept |
| Determines whether the specified object is equal to the current object. More... | |
| virtual size_t | get_hash_code () const noexcept |
| Serves as a hash function for a particular type. More... | |
| virtual type_object | get_type () const noexcept |
| Gets the type of the current instance. More... | |
| template<typename object_t > | |
| std::unique_ptr< object_t > | memberwise_clone () const noexcept |
| Creates a shallow copy of the current object. More... | |
| virtual xtd::ustring | to_string () const noexcept |
| Returns a sxd::ustring that represents the current object. More... | |
| 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. More... | |
| 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. More... | |
| Static Public Member Functions inherited from xtd::threading::event_wait_handle | |
| static event_wait_handle | open_existing (const ustring &name) |
| Opens the specified named synchronization event, if it already exists. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| static bool | reference_equals (const object &object_a, const object &object_b) noexcept |
| Determines whether the specified object instances are the same instance. More... | |
| Protected Member Functions inherited from xtd::threading::event_wait_handle | |
| bool | signal () override |
| Releases ownership of the specified wait_handle object. More... | |
| bool | wait (int32 milliseconds_timeout) override |
| wait ownership of the specified mutex object. More... | |
| 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. More... | |
Constructor & Destructor Documentation
◆ manual_reset_event()
|
inlineexplicit |
Initializes a new instance of the xtd::threading::manual_reset_event class with a bool value indicating whether to set the initial state to signaled.
- Parameters
-
initial_state true to set the initial state signaled; false to set the initial state to nonsignaled.
- Remarks
- If the initial state of a xtd::threading::manual_reset_event is signaled (that is, if it is created by passing true for initialState), threads that wait on the xtd::threading::manual_reset_event do not block. If the initial state is nonsignaled, threads block until the xtd::threading::event_wait_handle::set method is called.
The documentation for this class was generated from the following file:
- xtd.core/include/xtd/threading/manual_reset_event.h
Generated on Mon Oct 9 2023 14:42:16 for xtd by Gammasoft. All rights reserved.