EventWaitHandle Class

Represents a thread synchronization event.

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

No code example is currently available or this language may not be supported.

The EventWaitHandle type exposes the following members.

  NameDescription
Public propertySupported by Silverlight for Windows PhoneSupported by Xbox 360SafeWaitHandleGets or sets the native operating-system handle. (Inherited from WaitHandle.)
Top

  NameDescription
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360CloseWhen overridden in a derived class, releases all resources held by the current WaitHandle. (Inherited from WaitHandle.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360Dispose()Releases all resources used by the current instance of the WaitHandle class. (Inherited from WaitHandle.)
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360Dispose(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 Silverlight for Windows PhoneSupported by Xbox 360Equals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360FinalizeAllows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360GetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360GetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodSupported by Silverlight for Windows PhoneSupported by Xbox 360MemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ResetSets the state of the event to non-signaled, which causes threads to block.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360SetSets the state of the event to signaled, which allows one or more waiting threads to proceed.
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360ToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360WaitOne()Blocks the current thread until the current WaitHandle receives a signal. (Inherited from WaitHandle.)

In Silverlight for Windows Phone, this member is overridden by WaitOne().


In XNA Framework, this member is overridden by WaitOne().
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360WaitOne(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.)
Public methodSupported by Silverlight for Windows PhoneSupported by Xbox 360WaitOne(TimeSpan)Blocks the current thread until the current instance receives a signal, using a TimeSpan to specify the time interval. (Inherited from WaitHandle.)
Top

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.

NoteNote:

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.

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:

  1. 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 noteImportant 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.

  2. Calls the Set method on mref. This demonstrates that all the waiting threads are released at the same time.

  3. Starts two more threads to demonstrate that threads will not block on a ManualResetEvent as long as it remains signaled.

    NoteNote:

    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.

  4. Calls the Reset method on mref, and then starts another thread to demonstrate that threads once again block.

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

  6. 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 noteImportant 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.

No code example is currently available or this language may not be supported.

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

This type is thread safe.

Community Additions

ADD
Show: