xtd 0.2.0
Loading...
Searching...
No Matches
xtd::threading::auto_reset_event Class Reference
Inheritance diagram for xtd::threading::auto_reset_event:
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

Definition

Represents a thread synchronization event that, when signaled, resets automatically after releasing a single waiting thread. This class cannot be inherited.

Represents a thread synchronization event that, when signaled, resets automatically after releasing a...
Definition auto_reset_event.h:36
Represents a thread synchronization event.
Definition event_wait_handle.h:37
Header
#include <xtd/threading/auto_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).
A thread waits for a signal by calling xtd::threading::auto_reset_event::wWait_one. If the xtd::threading::auto_reset_event is in the non-signaled state, the thread blocks until xtd::threading::auto_reset_event::set is called.
Calling xtd::threading::auto_reset_event::set signals xtd::threading::auto_reset_event to release a waiting thread. xtd::threading::auto_reset_event remains signaled until a single waiting thread is released, and then automatically returns to the non-signaled state. If no threads are waiting, the state remains signaled indefinitely.
If a thread calls xtd::threading::wait_handle::wait_one while the xtd::threading::auto_reset_event is in the signaled state, the thread does not block. The xtd::threading::auto_reset_event releases the thread immediately and returns to the non-signaled state.
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
You can xtd::threading::auto_reset_event the initial state of an xtd::threading::auto_reset_event by passing a bool value to the constructor: true if the initial state is signaled and false otherwise.
AutoResetEvent can also be used with the static xtd::threading::wait_handle::wait_all and xtd::threading::wait_handle::wait_any methods.
Note
Unlike the xtd::threading::auto_reset_event class, the xtd::threading::event_wait_handle class provides access to named system synchronization events.
Examples
The following example shows how to use xtd::threading::auto_reset_event to release one thread at a time, by calling the xtd::threading::event_wait_handle::set method (on the base class) each time the user presses the Enter key. The example starts three threads, which wait on an xtd::threading::auto_reset_event that was created in the signaled state. The first thread is released immediately, because the xtd::threading::auto_reset_event is already in the signaled state. This resets the xtd::threading::auto_reset_event to the non-signaled state, so that subsequent threads block. The blocked threads are not released until the user releases them one at a time by pressing the Enter key. After the threads are released from the first xtd::threading::auto_reset_event, they wait on another xtd::threading::auto_reset_event that was created in the non-signaled state. All three threads block, so the xtd::threading::event_wait_handle::set method must be called three times to release them all.
#include <xtd/collections/generic/list>
#include <xtd/threading/auto_reset_event>
#include <xtd/threading/thread>
#include <xtd/console>
#include <xtd/startup>
using namespace xtd;
using namespace xtd::collections::generic;
using namespace xtd::threading;
namespace auto_reset_event_example {
class program {
public:
// The main entry point for the application.
static auto main() {
console::write_line("Press Enter to create three threads and start them.\r\n"
"The threads wait on auto_reset_event #1, which was created\r\n"
"in the signaled state, so the first thread is released.\r\n"
"This puts auto_reset_event #1 into the unsignaled state.");
console::read_line();
for (auto index = 1; index < 4; ++index) {
threads.emplace_back(thread_proc);
threads.back().name(string::format("Thread_{}", index));
threads.back().start();
}
thread::sleep(250_ms);
for (auto index = 0; index < 2; ++index) {
console::write_line("Press Enter to release another thread.");
console::read_line();
event_1.set();
thread::sleep(250_ms);
}
console::write_line("\r\nAll threads are now waiting on auto_reset_event #2.");
for (int i = 0; i < 3; i++) {
console::write_line("Press Enter to release a thread.");
console::read_line();
event_2.set();
thread::sleep(250_ms);
}
}
static void thread_proc() {
string name = thread::current_thread().name();
console::write_line("{0} waits on auto_reset_event #1.", name);
event_1.wait_one();
console::write_line("{0} is released from auto_reset_event #1.", name);
console::write_line("{0} waits on auto_reset_event #2.", name);
event_2.wait_one();
console::write_line("{0} is released from auto_reset_event #2.", name);
console::write_line("{0} ends.", name);
}
private:
inline static list<thread> threads = list<thread>(4);
inline static auto_reset_event event_1 {true};
inline static auto_reset_event event_2 {false};
};
}
startup_(auto_reset_event_example::program::main);
// This example produces output similar to the following:
//
// Press Enter to create three threads and start them.
// The threads wait on auto_reset_event #1, which was created
// in the signaled state, so the first thread is released.
// This puts auto_reset_event #1 into the unsignaled state.
//
// Thread_1 waits on auto_reset_event #1.
// Thread_1 is released from auto_reset_event #1.
// Thread_1 waits on auto_reset_event #2.
// Thread_2 waits on auto_reset_event #1.
// Thread_3 waits on auto_reset_event #1.
// Press Enter to release another thread.
//
// Thread_3 is released from auto_reset_event #1.
// Thread_3 waits on auto_reset_event #2.
// Press Enter to release another thread.
//
// Thread_2 is released from auto_reset_event #1.
// Thread_2 waits on auto_reset_event #2.
//
// All threads are now waiting on auto_reset_event #2.
// Press Enter to release a thread.
//
// Thread_1 is released from auto_reset_event #2.
// Thread_1 ends.
// Press Enter to release a thread.
//
// Thread_3 is released from auto_reset_event #2.
// Thread_3 ends.
// Press Enter to release a thread.
//
// Thread_2 is released from auto_reset_event #2.
// Thread_2 ends.
Represents a strongly typed list of objects that can be accessed by index. Provides methods to search...
Definition list.h:71
#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
@ i
The I key.
The xtd::collections::generic namespace contains interfaces and classes that define generic collectio...
Definition comparer.h:15
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
auto_reset_event.cpp, monitor_lock.cpp, timer.cpp, and wait_handle.cpp.

Public Constructors

 auto_reset_event ()=default
 Initializes a new instance of the xtd::threading::auto_reset_event class.
 
 auto_reset_event (bool initial_state)
 Initializes a new instance of the xtd::threading::auto_reset_event class with a bool value indicating whether to set the initial state to signaled.
 

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::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.
 
 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.
 
intptr handle () const noexcept override
 Gets the native operating system handle.
 
void handle (intptr value) override
 Sets the native operating system handle.
 
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.
 
- 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::event_wait_handle
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.
 
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.
 
- 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::event_wait_handle
bool signal () override
 Releases ownership of the specified wait_handle object.
 
bool wait (int32 milliseconds_timeout) override
 wait ownership of the specified mutex object.
 
- 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

◆ auto_reset_event() [1/2]

xtd::threading::auto_reset_event::auto_reset_event ( )
default

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

Remarks
The initial state is false.

◆ auto_reset_event() [2/2]

xtd::threading::auto_reset_event::auto_reset_event ( bool  initial_state)
inlineexplicit

Initializes a new instance of the xtd::threading::auto_reset_event class with a bool value indicating whether to set the initial state to signaled.

Parameters
initial_statetrue to set the initial state to signaled; false to set the initial state to non-signaled.

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