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/xtd>
 
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.add(thread {thread_proc});
        threads[threads.count() - 1].name(string::format("Thread_{}", index));
        threads[threads.count() - 1].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);
      }
      
      thread::join_all(threads);
    }
    
    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.

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 const intptr	invalid_handle
	Represents an invalid native operating system handle. This field is read-only.
static constexpr xtd::size	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.
	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.
auto	handle () const noexcept -> intptr override
	Gets the native operating system handle.
void	handle (intptr value) override
	Sets the native operating system handle.
auto	close () -> void override
	Releases all resources held by the current xtd::threading::wait_handle.
auto	compare_to (const event_wait_handle &value) const noexcept -> int32 override
auto	equals (const object &obj) const noexcept -> bool override
	Determines whether the specified object is equal to the current object.
auto	equals (const event_wait_handle &other) const noexcept -> bool override
	Determines whether the specified object is equal to the current object.
auto	reset () -> bool
	Sets the state of the event to nonsignaled, causing threads to block.
auto	set () -> bool
	Sets the state of the event to signaled, allowing one or more waiting threads to proceed.
	wait_handle ()=default
	Initializes a new instance of the xtd::threading::wait_handle class.
virtual auto	wait_one () -> bool
	Blocks the current thread until the current xtd::threading::wait_handle receives a signal.
virtual auto	wait_one (int32 milliseconds_timeout) -> bool
	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 auto	wait_one (const time_span &timeout) -> bool
	Blocks the current thread until the current instance receives a signal, using a xtd::time_span to measure the time interval.
	object ()=default
	Create a new instance of the ultimate base class object.
virtual xtd::size	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<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const
	Returns a xtd::string that represents the current object.
virtual int32	compare_to (const event_wait_handle &obj) const noexcept=0
	Compares the current instance with another object of the same type.
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 auto	open_existing (const string &name) -> event_wait_handle
	Opens the specified named synchronization event, if it already exists.
static auto	try_open_existing (const string &name, event_wait_handle &result) noexcept -> bool
	Opens the specified named synchronization event, if it already exists, and returns a value that indicates whether the operation succeeded.
static auto	signal_and_wait (wait_handle &to_signal, wait_handle &to_wait) -> bool
	Signals one xtd::threading::wait_handle and waits on another.
static auto	signal_and_wait (wait_handle &to_signal, wait_handle &to_wait, int32 milliseconds_timeout) -> bool
	Signals one xtd::threading::wait_handle and waits on another, specifying a time-out interval as a 32-bit signed integer.
static auto	signal_and_wait (wait_handle &to_signal, wait_handle &to_wait, const time_span &timeout) -> bool
	Signals one xtd::threading::wait_handle and waits on another, specifying a time-out interval as a time_span.
template<class collection_t>
static auto	wait_all (const collection_t &wait_handles) -> bool
	Waits for all the elements in the specified collection to receive a signal.
template<class collection_t>
static auto	wait_all (const collection_t &wait_handles, int32 milliseconds_timeout) -> bool
	Waits for all the elements in the specified collection to receive a signal, using an int32 value to measure the time interval.
template<class collection_t>
static auto	wait_all (const collection_t &wait_handles, const time_span &timeout) -> bool
	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<class collection_t>
static auto	wait_any (const collection_t &wait_handles) -> xtd::size
	Waits for any of the elements in the specified collection to receive a signal.
template<class collection_t>
static auto	wait_any (const collection_t &wait_handles, int32 milliseconds_timeout) -> xtd::size
	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<class collection_t>
static auto	wait_any (const collection_t &wait_handles, const time_span &timeout) -> xtd::size
	Waits for any of the elements in the specified collection to receive a signal, using a xtd::time_span to measure the time interval.
template<class object_a_t, class 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<class object_a_t, class 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.
auto	signal () -> bool override
	Releases ownership of the specified wait_handle object.
auto	wait (int32 milliseconds_timeout) -> bool override
	wait ownership of the specified mutex 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.hpp