EventWaitHandle Class
Assembly: mscorlib (in mscorlib.dll)
Note |
|---|
| The HostProtectionAttribute attribute applied to this class has the following Resources property value: Synchronization | ExternalThreading. The HostProtectionAttribute does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the HostProtectionAttribute class or SQL Server Programming and Host Protection Attributes. |
The EventWaitHandle class allows threads to communicate with each other by signaling. Typically, one or more threads block on an EventWaitHandle until an unblocked thread calls the Set method, releasing one or more of the blocked threads. A thread can signal an EventWaitHandle and then block on it, as an atomic operation, by calling the static (Shared in Visual Basic) System.Threading.WaitHandle.SignalAndWait method.
Note |
|---|
| The EventWaitHandle class provides access to named system synchronization events. |
The behavior of an EventWaitHandle that has been signaled depends on its reset mode. An EventWaitHandle created with the EventResetMode.AutoReset flag resets automatically when signaled, after releasing a single waiting thread. An EventWaitHandle created with the EventResetMode.ManualReset flag 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 attempts to wait on 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 on 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) System.Threading.WaitHandle.WaitAll and System.Threading.WaitHandle.WaitAny methods.
For more information about thread synchronization mechanisms, see EventWaitHandle, AutoResetEvent, and ManualResetEvent.
The following code example uses the SignalAndWait(WaitHandle,WaitHandle) method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task.
The example starts five threads and allows them to block on an EventWaitHandle created with the EventResetMode.AutoReset flag, then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an EventWaitHandle created with the EventResetMode.ManualReset flag.
Imports System Imports System.Threading Public Class Example ' The EventWaitHandle used to demonstrate the difference ' between AutoReset and ManualReset synchronization events. ' Private Shared ewh As EventWaitHandle ' A counter to make sure all threads are started and ' blocked before any are released. A Long is used to show ' the use of the 64-bit Interlocked methods. ' Private Shared threadCount As Long = 0 ' An AutoReset event that allows the main thread to block ' until an exiting thread has decremented the count. ' Private Shared clearCount As New EventWaitHandle(False, _ EventResetMode.AutoReset) <MTAThread> _ Public Shared Sub Main() ' Create an AutoReset EventWaitHandle. ' ewh = New EventWaitHandle(False, EventResetMode.AutoReset) ' Create and start five numbered threads. Use the ' ParameterizedThreadStart delegate, so the thread ' number can be passed as an argument to the Start ' method. For i As Integer = 0 To 4 Dim t As New Thread(AddressOf ThreadProc) t.Start(i) Next i ' Wait until all the threads have started and blocked. ' When multiple threads use a 64-bit value on a 32-bit ' system, you must access the value through the ' Interlocked class to guarantee thread safety. ' While Interlocked.Read(threadCount) < 5 Thread.Sleep(500) End While ' Release one thread each time the user presses ENTER, ' until all threads have been released. ' While Interlocked.Read(threadCount) > 0 Console.WriteLine("Press ENTER to release a waiting thread.") Console.ReadLine() ' SignalAndWait signals the EventWaitHandle, which ' releases exactly one thread before resetting, ' because it was created with AutoReset mode. ' SignalAndWait then blocks on clearCount, to ' allow the signaled thread to decrement the count ' before looping again. ' WaitHandle.SignalAndWait(ewh, clearCount) End While Console.WriteLine() ' Create a ManualReset EventWaitHandle. ' ewh = New EventWaitHandle(False, EventResetMode.ManualReset) ' Create and start five more numbered threads. ' For i As Integer = 0 To 4 Dim t As New Thread(AddressOf ThreadProc) t.Start(i) Next i ' Wait until all the threads have started and blocked. ' While Interlocked.Read(threadCount) < 5 Thread.Sleep(500) End While ' Because the EventWaitHandle was created with ' ManualReset mode, signaling it releases all the ' waiting threads. ' Console.WriteLine("Press ENTER to release the waiting threads.") Console.ReadLine() ewh.Set() End Sub Public Shared Sub ThreadProc(ByVal data As Object) Dim index As Integer = CInt(data) Console.WriteLine("Thread {0} blocks.", data) ' Increment the count of blocked threads. Interlocked.Increment(threadCount) ' Wait on the EventWaitHandle. ewh.WaitOne() Console.WriteLine("Thread {0} exits.", data) ' Decrement the count of blocked threads. Interlocked.Decrement(threadCount) ' After signaling ewh, the main thread blocks on ' clearCount until the signaled thread has ' decremented the count. Signal it now. ' clearCount.Set() End Sub End Class
import System.*;
import System.Threading.*;
public class Example
{
// The EventWaitHandle used to demonstrate the difference
// between AutoReset and ManualReset synchronization events.
//
private static EventWaitHandle ewh;
// A counter to make sure all threads are started and
// blocked before any are released. A Long is used to show
// the use of the 64-bit Interlocked methods.
//
private static long threadCount = 0;
// An AutoReset event that allows the main thread to block
// until an exiting thread has decremented the count.
//
private static EventWaitHandle clearCount = new EventWaitHandle(false,
EventResetMode.AutoReset);
/** @attribute MTAThread()
*/
public static void main(String[] args)
{
// Create an AutoReset EventWaitHandle.
//
ewh = new EventWaitHandle(false, EventResetMode.AutoReset);
// Create and start five numbered threads. Use the
// ParameterizedThreadStart delegate, so the thread
// number can be passed as an argument to the Start
// method.
for (int i = 0; i <= 4; i++) {
System.Threading.Thread t = new System.Threading.Thread(new
ParameterizedThreadStart(ThreadProc));
t.Start((Int32)i);
}
// Wait until all the threads have started and blocked.
// When multiple threads use a 64-bit value on a 32-bit
// system, you must access the value through the
// Interlocked class to guarantee thread safety.
//
while (Interlocked.Read(threadCount) < 5) {
System.Threading.Thread.Sleep(500);
}
// Release one thread each time the user presses ENTER,
// until all threads have been released.
//
while (Interlocked.Read(threadCount) > 0) {
Console.WriteLine("Press ENTER to release a waiting thread.");
Console.ReadLine();
// SignalAndWait signals the EventWaitHandle, which
// releases exactly one thread before resetting,
// because it was created with AutoReset mode.
// SignalAndWait then blocks on clearCount, to
// allow the signaled thread to decrement the count
// before looping again.
//
WaitHandle.SignalAndWait(ewh, clearCount);
}
Console.WriteLine();
// Create a ManualReset EventWaitHandle.
//
ewh = new EventWaitHandle(false, EventResetMode.ManualReset);
// Create and start five more numbered threads.
//
for (int i = 0; i <= 4; i++) {
System.Threading.Thread t = new System.Threading.Thread(new
ParameterizedThreadStart(ThreadProc));
t.Start((Int32)i);
}
// Wait until all the threads have started and blocked.
//
while (Interlocked.Read(threadCount) < 5) {
System.Threading.Thread.Sleep(500);
}
// Because the EventWaitHandle was created with
// ManualReset mode, signaling it releases all the
// waiting threads.
//
Console.WriteLine("Press ENTER to release the waiting threads.");
Console.ReadLine();
ewh.Set();
} //main
public static void ThreadProc(Object data)
{
int index = System.Convert.ToInt32(data);
Console.WriteLine("Thread {0} blocks.", data);
// Increment the count of blocked threads.
Interlocked.Increment(threadCount);
// Wait on the EventWaitHandle.
ewh.WaitOne();
Console.WriteLine("Thread {0} exits.", data);
// Decrement the count of blocked threads.
Interlocked.Decrement(threadCount);
// After signaling ewh, the main thread blocks on
// clearCount until the signaled thread has
// decremented the count. Signal it now.
//
clearCount.Set();
} //ThreadProc
} //Example
System.MarshalByRefObject
System.Threading.WaitHandle
System.Threading.EventWaitHandle
System.Threading.AutoResetEvent
System.Threading.ManualResetEvent
Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.
Note