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/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");
      
      for(auto i = 0; i <= 2; ++i) {
        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");
      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.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");
      console::read_line();
      
      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.");
      console::read_line();
      
      mre.set();
    }
    
  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.
    inline static manual_reset_event mre {false};
    
    static void thread_proc() {
      ustring 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.

Examples

manual_reset_event.cpp.

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

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