xtd::threading::auto_reset_event Class Reference

Inheritance diagram for xtd::threading::auto_reset_event:

Definition

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

class auto_reset_event : public xtd::threading::event_wait_handle

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/threading/auto_reset_event>
#include <xtd/threading/thread>
#include <xtd/console>
#include <xtd/startup>
 
using namespace xtd;
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(ustring::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() {
      ustring 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 std::vector<thread> threads = std::vector<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.

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 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.
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.
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::event_wait_handle
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.
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::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_state

true 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:

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