EventWaitHandle Class
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
Represents a thread synchronization event.
System.Threading::WaitHandle
System.Threading::EventWaitHandle
System.Threading::AutoResetEvent
System.Threading::ManualResetEvent
Assembly: mscorlib (in mscorlib.dll)
The EventWaitHandle type exposes the following members.
| Name | Description | |
|---|---|---|
 | EventWaitHandle(Boolean, EventResetMode) | Initializes a new instance of the EventWaitHandle class, specifying whether the wait handle is initially signaled, and whether it resets automatically or manually. |
| EventWaitHandle(Boolean, EventResetMode, String) | Security Critical. Initializes a new instance of the EventWaitHandle 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. |
| EventWaitHandle(Boolean, EventResetMode, String, Boolean%) | Security Critical. Initializes a new instance of the EventWaitHandle 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 Boolean variable whose value after the call indicates whether the named system event was created. |
| Name | Description | |
|---|---|---|
 | SafeWaitHandle | Gets or sets the native operating-system handle. (Inherited from WaitHandle.) |
| Name | Description | |
|---|---|---|
| Close | When overridden in a derived class, releases all resources held by the current WaitHandle. (Inherited from WaitHandle.) |
| Dispose() | Releases all resources used by the current instance of the WaitHandle class. (Inherited from WaitHandle.) |
 | Dispose(Boolean) | When overridden in a derived class, releases the unmanaged resources used by the WaitHandle, and optionally releases the managed resources. (Inherited from WaitHandle.) |
| Equals(Object) | Determines whether the specified Object is equal to the current Object. (Inherited from Object.) |
| Finalize | Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.) |
| GetHashCode | Serves as a hash function for a particular type. (Inherited from Object.) |
| GetType | Gets the Type of the current instance. (Inherited from Object.) |
| MemberwiseClone | Creates a shallow copy of the current Object. (Inherited from Object.) |
 | OpenExisting | Security Critical. Opens the specified named synchronization event, if it already exists. |
| Reset | Sets the state of the event to non-signaled, which causes threads to block. |
| Set | Sets the state of the event to signaled, which allows one or more waiting threads to proceed. |
| ToString | Returns a string that represents the current object. (Inherited from Object.) |
| TryOpenExisting | Security Critical. Opens the specified named synchronization event, if it already exists, and returns a value that indicates whether the operation succeeded. |
| WaitOne() | Blocks the current thread until the current WaitHandle receives a signal. (Inherited from WaitHandle.) |
| WaitOne(Int32) | Blocks the current thread until the current WaitHandle receives a signal, using 32-bit signed integer to specify the time interval. (Inherited from WaitHandle.) |
| WaitOne(TimeSpan) | Blocks the current thread until the current instance receives a signal, using a TimeSpan to specify the time interval. (Inherited from WaitHandle.) |
EventWaitHandle is the base class for AutoResetEvent and ManualResetEvent.
Thread synchronization events enable threads to communicate with each other by signaling. Typically, one or more threads block on an event object until an unblocked thread calls the Set method, releasing one or more of the blocked threads.
 Note: |
|---|
Thread synchronization events are not .NET Framework events. Thread synchronization events have no event handlers, for example. For historical reasons, the term "event" has been applied to two completely different technologies. |
The behavior of an event that has been signaled depends on its reset mode. An AutoResetEvent resets automatically when signaled, after releasing a single waiting thread. By contrast, a ManualResetEvent remains signaled until its Reset method is called.
Automatic reset events provide exclusive access to a resource. If an automatic reset event is signaled when no threads are waiting, it remains signaled until a thread tries to wait for it. The event releases the thread and immediately resets, blocking subsequent threads.
Manual reset events are like gates. When the event is not signaled, threads that wait for it will block. When the event is signaled, all waiting threads are released, and the event remains signaled (that is, subsequent waits do not block) until its Reset method is called. Manual reset events are useful when one thread must complete an activity before other threads can proceed.
EventWaitHandle objects can be used with the static (Shared in Visual Basic) WaitHandle::WaitAll and WaitHandle::WaitAny methods.
For more information about thread synchronization mechanisms, see EventWaitHandle, AutoResetEvent, and ManualResetEvent.
The following example demonstrates the use of both kinds of EventWaitHandle: AutoResetEvent and ManualResetEvent. The example shows several uses of each.
The example is run on a separate thread from the main UI thread, because event wait handles synchronize threads by blocking them. The UI thread should not be blocked, because that makes it unresponsive to user actions. Blocking the UI thread also blocks any cross-thread calls to UI elements that you make using the Dispatcher, a technique that this example relies on.
| Note: |
|---|
To run this example, see Building examples that have static TextBlock controls for Windows Phone 8. |
The example begins with a Demo method that does the following:
Displays an introductory message.
Starts the thread that controls the demo.
Hooks up an event handler (MouseUp) for the MouseLeftButtonUp event.
The event handler for the MouseLeftButtonUp event calls the Set method on an AutoResetEvent named areSyncDemoThread, to signal the next step of the demo to proceed. An AutoResetEvent is the best choice here, because it automatically resets after it has been signaled.
The DemoThread method, which is the thread procedure that controls the demo, performs the following steps:
Starts three threads and passes an AutoResetEvent to each of them. DemoThread uses the WaitHandle::WaitAll method to block until all three threads are queued waiting for mref, which is a ManualResetEvent.
The thread procedure that is used by these threads posts a message to the TextBlock before it calls the Set method on its AutoResetEvent. The thread then calls WaitOne on mref, blocking until DemoThread releases it. The thread procedure posts an "end" message to the TextBlock and signals the AutoResetEvent again to let DemoThread know that the message has been posted. Here, too, AutoResetEvent is the best choice because it resets automatically.
Important Note:The example displays its output in a TextBlock on the UI thread. To access the TextBlock from the callback thread, the example uses the Dispatcher property to obtain a Dispatcher object for the TextBlock, and then uses the Dispatcher::BeginInvoke method to make the cross-thread call. In this example, the displayHelper delegate is used to invoke the DisplayOutput helper method.
Calls the Set method on mref. This demonstrates that all the waiting threads are released at the same time.
Starts two more threads to demonstrate that threads will not block on a ManualResetEvent as long as it remains signaled.
Note:When these threads are created, they are not passed an AutoResetEvent because they do not need to notify DemoThread when they call WaitOne. Instead, DemoThread uses the Thread::Join method to wait until both threads are finished.
Calls the Reset method on mref, and then starts another thread to demonstrate that threads once again block.
There are two parts to this step. First, the thread from step 4 is released and the TextBlock contents are cleared. Second, an AutoResetEvent (in the variable named wait) is signaled when there are no threads waiting for it. It remains in the signaled state while DemoThread queues and releases three more threads, this time using the ThreadProcARE method for the thread procedure. The first thread to wait for the signaled AutoResetEvent is the only one that does not block, because the AutoResetEvent returns to the non-signaled state as soon as it releases a thread.
The ThreadProcARE method receives an array that contains two AutoResetEvent objects. It uses the first AutoResetEvent to signal DemoThread when it has posted its messages to the TextBlock, and the second AutoResetEvent to signal that it is ending. DemoThread uses the WaitHandle::WaitAny method to detect that at least one thread has ended.
Releases the threads that are still waiting on the AutoResetEvent in the variable wait by calling Set, and disposes of the static wait handles. If the threads are not released before DemoThread ends and the variable wait goes out of scope, they will never be released, they will never run, and their resources will not be reclaimed until the application ends. Whether this is important to you depends on the nature of your application.
Important Note:When you release multiple threads that are blocked on an AutoResetEvent, remember that if two calls to Set occur too close together, the second call might not release a thread. In this example, WaitHandle::WaitAny is used to ensure that the first thread is released before Set is called again. If you comment out WaitHandle::WaitAny and run the program several times, you might observe this behavior.