EventWaitHandle Class

Represents a thread synchronization event.

Namespace:  System.Threading
Assembly:  mscorlib (in mscorlib.dll)

[ComVisibleAttribute(true)]
[HostProtectionAttribute(SecurityAction.LinkDemand, Synchronization = true, 
	ExternalThreading = true)]
public class EventWaitHandle : WaitHandle

The EventWaitHandle type exposes the following members.

  NameDescription
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsEventWaitHandle(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.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsEventWaitHandle(Boolean, EventResetMode, String)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.
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsEventWaitHandle(Boolean, EventResetMode, String, Boolean)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.
Public methodEventWaitHandle(Boolean, EventResetMode, String, Boolean, EventWaitHandleSecurity)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, a Boolean variable whose value after the call indicates whether the named system event was created, and the access control security to be applied to the named event if it is created.
Top

  NameDescription
Public propertySupported by the XNA FrameworkHandle Obsolete. Gets or sets the native operating system handle. (Inherited from WaitHandle.)
Public propertySafeWaitHandleGets or sets the native operating system handle. (Inherited from WaitHandle.)
Top

  NameDescription
Public methodSupported by the XNA FrameworkCloseReleases all resources held by the current WaitHandle. (Inherited from WaitHandle.)

In XNA Framework, this member is overridden by Close().
Public methodCreateObjRefCreates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject.)
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsDispose()Releases all resources used by the current instance of the WaitHandle class. (Inherited from WaitHandle.)
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsDispose(Boolean)When overridden in a derived class, releases the unmanaged resources used by the WaitHandle, and optionally releases the managed resources. (Inherited from WaitHandle.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodSupported by the XNA FrameworkFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)

In XNA Framework, this member is overridden by Finalize().
Public methodGetAccessControlGets an EventWaitHandleSecurity object that represents the access control security for the named system event represented by the current EventWaitHandle object.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetLifetimeServiceRetrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodInitializeLifetimeServiceObtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject.)
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsMemberwiseClone()Creates a shallow copy of the current Object. (Inherited from Object.)
Protected methodMemberwiseClone(Boolean)Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject.)
Public methodStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsOpenExisting(String)Opens the specified named synchronization event, if it already exists.
Public methodStatic memberOpenExisting(String, EventWaitHandleRights)Opens the specified named synchronization event, if it already exists, with the desired security access.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsResetSets the state of the event to nonsignaled, causing threads to block.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsSetSets the state of the event to signaled, allowing one or more waiting threads to proceed.
Public methodSetAccessControlSets the access control security for a named system event.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodStatic memberSupported in .NET for Windows Store appsTryOpenExisting(String, EventWaitHandle)Opens the specified named synchronization event, if it already exists, and returns a value that indicates whether the operation succeeded.
Public methodStatic memberTryOpenExisting(String, EventWaitHandleRights, EventWaitHandle)Opens the specified named synchronization event, if it already exists, with the desired security access, and returns a value that indicates whether the operation succeeded.
Public methodSupported by the XNA FrameworkWaitOne()Blocks the current thread until the current WaitHandle receives a signal. (Inherited from WaitHandle.)

In XNA Framework, this member is overridden by WaitOne().
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsWaitOne(Int32)Blocks the current thread until the current WaitHandle receives a signal, using a 32-bit signed integer to specify the time interval. (Inherited from WaitHandle.)
Public methodSupported by Portable Class LibrarySupported in .NET for Windows Store appsWaitOne(TimeSpan)Blocks the current thread until the current instance receives a signal, using a TimeSpan to specify the time interval. (Inherited from WaitHandle.)
Public methodSupported by the XNA FrameworkWaitOne(Int32, Boolean)Blocks the current thread until the current WaitHandle receives a signal, using a 32-bit signed integer to specify the time interval and specifying whether to exit the synchronization domain before the wait. (Inherited from WaitHandle.)

In XNA Framework, this member is overridden by WaitOne(Int32, Boolean).
Public methodWaitOne(TimeSpan, Boolean)Blocks the current thread until the current instance receives a signal, using a TimeSpan to specify the time interval and specifying whether to exit the synchronization domain before the wait. (Inherited from WaitHandle.)
Top

  NameDescription
Explicit interface implemetationPrivate methodSupported by the XNA FrameworkIDisposable.DisposeInfrastructure. Releases all resources used by the WaitHandle. (Inherited from WaitHandle.)
Top

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, by calling the static (Shared in Visual Basic) WaitHandle.SignalAndWait method.

NoteNote

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) WaitHandle.WaitAll and WaitHandle.WaitAny methods.

For more information about thread synchronization mechanisms, see EventWaitHandle, AutoResetEvent, CountdownEvent, ManualResetEvent.

NoteNote

The HostProtectionAttribute attribute applied to this type or member 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 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.

using System;
using 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);

    [MTAThread]
    public static void 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 (int i = 0; i <= 4; i++)
        {
            Thread t = new Thread(
                new ParameterizedThreadStart(ThreadProc)
            );
            t.Start(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(ref threadCount) < 5)
        {
            Thread.Sleep(500);
        }

        // Release one thread each time the user presses ENTER, 
        // until all threads have been released. 
        // 
        while (Interlocked.Read(ref 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++)
        {
            Thread t = new Thread(
                new ParameterizedThreadStart(ThreadProc)
            );
            t.Start(i);
        }

        // Wait until all the threads have started and blocked. 
        // 
        while (Interlocked.Read(ref threadCount) < 5)
        {
            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();

    }

    public static void ThreadProc(object data)
    {
        int index = (int) data;

        Console.WriteLine("Thread {0} blocks.", data);
        // Increment the count of blocked threads.
        Interlocked.Increment(ref threadCount);

        // Wait on the EventWaitHandle.
        ewh.WaitOne();

        Console.WriteLine("Thread {0} exits.", data);
        // Decrement the count of blocked threads.
        Interlocked.Decrement(ref threadCount);

        // After signaling ewh, the main thread blocks on 
        // clearCount until the signaled thread has  
        // decremented the count. Signal it now. 
        //
        clearCount.Set();
    }
}

.NET Framework

Supported in: 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone Silverlight 8.1, Windows Phone Silverlight 8

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

This type is thread safe.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft