xtd::threading::manual_reset_event Class Reference

Inheritance diagram for xtd::threading::manual_reset_event:

Definition

Represents a thread synchronization event that, when signaled, must be reset manually. This class cannot be inherited.

class manual_reset_event : public xtd::threading::event_wait_handle

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/xtd>
 
namespace manual_reset_event_example {
  class program {
  public:
    static void main() {
      console::write_line("\nStart 3 named threads that block on a ManualresetEvent:\n");
      
      for(auto i = 0; i <= 2; ++i) {
        threads.add(thread {thread_proc});
        threads[threads.count() - 1].name(string::format("Thread_{}", i));
        threads[threads.count() - 1].start();
      }
      
      thread::sleep(500);
      console::write_line("\nWhen all three threads have started, press Enter to call set()"
                          "\nto release all the threads.\n");
      console::read_line();
      
      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");
      console::read_line();
      
      for(auto i = 3; i <= 4; ++i) {
        threads.add(thread {thread_proc});
        threads[threads.count() - 1].name(string::format("Thread_{}", i));
        threads[threads.count() - 1].start();
      }
      
      thread::sleep(500);
      console::write_line("\nPress Enter to call reset(), so that threads once again block"
                          "\nwhen they call WaitOne().\n");
      console::read_line();
      
      mre.reset();
      
      // Start a thread that waits on the ManualresetEvent.
      threads.add(thread {thread_proc});
      threads[threads.count() - 1].name("Thread_5");
      threads[threads.count() - 1].start();
 
      thread::sleep(500);
      console::write_line("\nPress Enter to call set() and conclude the demo.");
      console::read_line();
      
      mre.set();
    }
    
  private:
    inline static list<thread> threads = list<thread>(4);
 
    // mre is used to block and release threads manually. It is
    // created in the unsignaled state.
    inline static manual_reset_event mre {false};
    
    static void thread_proc() {
      string name = thread::current_thread().name();
      
      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.

Public Constructors
	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.

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

manual_reset_event()

xtd::threading::manual_reset_event::manual_reset_event ( bool initial_state )

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