Export (0) Print
Expand All

WaitHandle Class

Encapsulates operating system–specific objects that wait for exclusive access to shared resources.

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

[ComVisibleAttribute(true)]
public ref class WaitHandle abstract : public MarshalByRefObject, 
	IDisposable

The WaitHandle type exposes the following members.

  NameDescription
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibraryWaitHandleInitializes a new instance of the WaitHandle class.
Top

  NameDescription
Public propertySupported by the XNA FrameworkHandle Obsolete. Gets or sets the native operating system handle.
Public propertySafeWaitHandleGets or sets the native operating system handle.
Top

  NameDescription
Public methodSupported by the XNA FrameworkCloseReleases all resources held by the current WaitHandle.
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 LibraryDispose()Releases all resources used by the current instance of the WaitHandle class.
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibraryDispose(Boolean)When overridden in a derived class, releases the unmanaged resources used by the WaitHandle, and optionally releases the managed resources.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodSupported by the XNA FrameworkSupported by Portable Class LibraryFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryGetHashCodeServes 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 LibraryGetTypeGets 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 LibraryMemberwiseClone()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 memberSignalAndWait(WaitHandle, WaitHandle)Signals one WaitHandle and waits on another.
Public methodStatic memberSignalAndWait(WaitHandle, WaitHandle, Int32, Boolean)Signals one WaitHandle and waits on another, specifying a time-out interval as a 32-bit signed integer and specifying whether to exit the synchronization domain for the context before entering the wait.
Public methodStatic memberSignalAndWait(WaitHandle, WaitHandle, TimeSpan, Boolean)Signals one WaitHandle and waits on another, specifying the time-out interval as a TimeSpan and specifying whether to exit the synchronization domain for the context before entering the wait.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodStatic memberSupported by Portable Class LibraryWaitAll(array<WaitHandle>)Waits for all the elements in the specified array to receive a signal.
Public methodStatic memberSupported by Portable Class LibraryWaitAll(array<WaitHandle>, Int32)Waits for all the elements in the specified array to receive a signal, using an Int32 value to specify the time interval.
Public methodStatic memberSupported by Portable Class LibraryWaitAll(array<WaitHandle>, TimeSpan)Waits for all the elements in the specified array to receive a signal, using a TimeSpan value to specify the time interval.
Public methodStatic memberWaitAll(array<WaitHandle>, Int32, Boolean)Waits for all the elements in the specified array to receive a signal, using an Int32 value to specify the time interval and specifying whether to exit the synchronization domain before the wait.
Public methodStatic memberWaitAll(array<WaitHandle>, TimeSpan, Boolean)Waits for all the elements in the specified array to receive a signal, using a TimeSpan value to specify the time interval, and specifying whether to exit the synchronization domain before the wait.
Public methodStatic memberSupported by Portable Class LibraryWaitAny(array<WaitHandle>)Waits for any of the elements in the specified array to receive a signal.
Public methodStatic memberSupported by Portable Class LibraryWaitAny(array<WaitHandle>, Int32)Waits for any of the elements in the specified array to receive a signal, using a 32-bit signed integer to specify the time interval.
Public methodStatic memberSupported by Portable Class LibraryWaitAny(array<WaitHandle>, TimeSpan)Waits for any of the elements in the specified array to receive a signal, using a TimeSpan to specify the time interval.
Public methodStatic memberWaitAny(array<WaitHandle>, Int32, Boolean)Waits for any of the elements in the specified array to receive a signal, using a 32-bit signed integer to specify the time interval, and specifying whether to exit the synchronization domain before the wait.
Public methodStatic memberWaitAny(array<WaitHandle>, TimeSpan, Boolean)Waits for any of the elements in the specified array to receive a signal, using a TimeSpan to specify the time interval and specifying whether to exit the synchronization domain before the wait.
Public methodSupported by the XNA FrameworkSupported by Portable Class LibraryWaitOne()Blocks the current thread until the current WaitHandle receives a signal.
Public methodSupported by Portable Class LibraryWaitOne(Int32)Blocks the current thread until the current WaitHandle receives a signal, using a 32-bit signed integer to specify the time interval.
Public methodSupported by Portable Class LibraryWaitOne(TimeSpan)Blocks the current thread until the current instance receives a signal, using a TimeSpan to specify the time interval.
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.
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.
Top

  NameDescription
Public Extension MethodGetSafeWaitHandle()Overloaded. Gets the safe handle for a native operating system wait handle. (Defined by WaitHandleExtensions.)
Public Extension MethodGetSafeWaitHandle()Overloaded. (Defined by WaitHandleExtensions.)
Public Extension MethodSetSafeWaitHandle(SafeWaitHandle)Overloaded. Sets a safe handle for a native operating system wait handle. (Defined by WaitHandleExtensions.)
Public Extension MethodSetSafeWaitHandle(SafeWaitHandle)Overloaded. (Defined by WaitHandleExtensions.)
Top

  NameDescription
Protected fieldStatic memberSupported by the XNA FrameworkSupported by Portable Class LibraryInvalidHandleRepresents an invalid native operating system handle. This field is read-only.
Public fieldStatic memberSupported by Portable Class LibraryWaitTimeoutIndicates that a WaitAny operation timed out before any of the wait handles were signaled. This field is constant.
Top

  NameDescription
Explicit interface implemetationPrivate methodSupported by the XNA FrameworkIDisposable::DisposeInfrastructure. Releases all resources used by the WaitHandle.
Top

This class is typically used as a base class for synchronization objects. Classes derived from WaitHandle define a signaling mechanism to indicate taking or releasing access to a shared resource, but use the inherited WaitHandle methods to block while waiting for access to shared resources.

Important noteImportant

This type implements the IDisposable interface. When you have finished using the type or a type derived from it, you should dispose of it either directly or indirectly. To dispose of the type directly, call its Close method in a try/catch block. To dispose of it indirectly, use a language construct such as using (in C#) or Using (in Visual Basic). For more information, see the “Using an Object that Implements IDisposable” section in the IDisposable interface topic.

Use the static methods of this class to block a thread until one or more synchronization objects receive a signal.

WaitHandle implements the Dispose pattern. See Dispose Pattern. When you derive from WaitHandle, use the SafeWaitHandle property to store your native handle operating system handle. You do not need to override the protected Dispose method unless you use additional unmanaged resources.

The following code example shows how two threads can do background tasks while the Main thread waits for the tasks to complete using the static WaitAny and WaitAll methods of the WaitHandle class.

using namespace System;
using namespace System::Threading;

public ref class WaitHandleExample
{
    // Define a random number generator for testing. 
private:
    static Random^ random = gcnew Random();
public:
    static void DoTask(Object^ state)
    {
        AutoResetEvent^ autoReset = (AutoResetEvent^) state;
        int time = 1000 * random->Next(2, 10);
        Console::WriteLine("Performing a task for {0} milliseconds.", time);
        Thread::Sleep(time);
        autoReset->Set();
    }
};

int main()
{
    // Define an array with two AutoResetEvent WaitHandles. 
    array<WaitHandle^>^ handles = gcnew array<WaitHandle^> {
        gcnew AutoResetEvent(false), gcnew AutoResetEvent(false)};

    // Queue up two tasks on two different threads; 
    // wait until all tasks are completed.
    DateTime timeInstance = DateTime::Now;
    Console::WriteLine("Main thread is waiting for BOTH tasks to " +
        "complete.");
    ThreadPool::QueueUserWorkItem(
        gcnew WaitCallback(WaitHandleExample::DoTask), handles[0]);
    ThreadPool::QueueUserWorkItem(
        gcnew WaitCallback(WaitHandleExample::DoTask), handles[1]);
    WaitHandle::WaitAll(handles);
    // The time shown below should match the longest task.
    Console::WriteLine("Both tasks are completed (time waited={0})",
        (DateTime::Now - timeInstance).TotalMilliseconds);

    // Queue up two tasks on two different threads; 
    // wait until any tasks are completed.
    timeInstance = DateTime::Now;
    Console::WriteLine();
    Console::WriteLine("The main thread is waiting for either task to " +
        "complete.");
    ThreadPool::QueueUserWorkItem(
        gcnew WaitCallback(WaitHandleExample::DoTask), handles[0]);
    ThreadPool::QueueUserWorkItem(
        gcnew WaitCallback(WaitHandleExample::DoTask), handles[1]);
    int index = WaitHandle::WaitAny(handles);
    // The time shown below should match the shortest task.
    Console::WriteLine("Task {0} finished first (time waited={1}).",
        index + 1, (DateTime::Now - timeInstance).TotalMilliseconds);
}

// This code produces the following sample output. 
// 
// Main thread is waiting for BOTH tasks to complete. 
// Performing a task for 7000 milliseconds. 
// Performing a task for 4000 milliseconds. 
// Both tasks are completed (time waited=7064.8052) 

// The main thread is waiting for either task to complete. 
// Performing a task for 2000 milliseconds. 
// Performing a task for 2000 milliseconds. 
// Task 1 finished first (time waited=2000.6528).

.NET Framework

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

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

XNA Framework

Supported in: 3.0, 2.0, 1.0

Portable Class Library

Supported in: Portable Class Library

Supported in: Windows Phone 8.1

Supported in: Windows Phone Silverlight 8.1

Supported in: Windows Phone Silverlight 8

This type is thread safe.

Show:
© 2015 Microsoft