System.Threading.WaitHandle Class

Summary

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

C# Syntax:

public abstract class WaitHandle : MarshalByRefObject, IDisposable

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 exclusive access to a shared resource, but use the inherited WaitHandle methods to block while waiting for access to shared resources.

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

System.Threading Namespace

System.Threading.WaitHandle Member List:

Public Constructors

ctor #1

Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the WaitHandle class.

Public Fields

WaitTimeout

Indicates that a WaitHandle.WaitAny operation has timed out before any of the wait handles fire. This field is constant.

Public Properties

Handle

Read-write Gets or sets the native operating system handle.

Public Methods

Close	When overridden in a derived class, releases all resources held by the current WaitHandle.
CreateObjRef (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.CreateObjRef Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetLifetimeService (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.GetLifetimeService Retrieves the current lifetime service object that controls the lifetime policy for this instance.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
InitializeLifetimeService (inherited from System.MarshalByRefObject)	See base class member description: System.MarshalByRefObject.InitializeLifetimeService Obtains a lifetime service object to control the lifetime policy for this instance.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.
WaitAll	Overloaded: WaitAll(WaitHandle[] waitHandles) Waits for all of the elements in the specified array to receive a signal.
WaitAll	Overloaded: WaitAll(WaitHandle[] waitHandles, int millisecondsTimeout, bool exitContext) Waits for all of the elements in the specified array to receive a signal, using an Int32 value to measure the time interval and specifying whether to exit the synchronization domain before the wait.
WaitAll	Overloaded: WaitAll(WaitHandle[] waitHandles, TimeSpan timeout, bool exitContext) Waits for all of the elements in the specified array to receive a signal, using a TimeSpan value to measure the time interval and specifying whether to exit the synchronization domain before the wait.
WaitAny	Overloaded: WaitAny(WaitHandle[] waitHandles) Waits for any of the elements in the specified array to receive a signal.
WaitAny	Overloaded: WaitAny(WaitHandle[] waitHandles, int millisecondsTimeout, bool exitContext) Waits for any of the elements in the specified array to receive a signal, using a 32-bit signed integer to measure the time interval, and specifying whether to exit the synchronization domain before the wait.
WaitAny	Overloaded: WaitAny(WaitHandle[] waitHandles, TimeSpan timeout, bool exitContext) Waits for any of the elements in the specified array to receive a signal, using a TimeSpan to measure the time interval and specifying whether to exit the synchronization domain before the wait.
WaitOne	Overloaded: WaitOne() When overridden in a derived class, blocks the current thread until the current WaitHandle receives a signal.
WaitOne	Overloaded: WaitOne(int millisecondsTimeout, bool exitContext) When overridden in a derived class, blocks the current thread until the current WaitHandle receives a signal, using 32-bit signed integer to measure the time interval and specifying whether to exit the synchronization domain before the wait.
WaitOne	Overloaded: WaitOne(TimeSpan timeout, bool exitContext) When overridden in a derived class, blocks the current thread until the current instance receives a signal, using a TimeSpan to measure the time interval and specifying whether to exit the synchronization domain before the wait.

Protected Fields

InvalidHandle

Represents an invalid handle that was passed to a method. This field is read-only.

Protected Methods

Dispose	When overridden in a derived class, releases the unmanaged resources used by the WaitHandle, and optionally releases the managed resources.
Finalize	Overridden: Releases the resources held by the current instance.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.MarshalByRefObject
• System.Threading.WaitHandle
  • System.Threading.AutoResetEvent
  • System.Threading.ManualResetEvent
  • System.Threading.Mutex

System.Threading.WaitHandle Member Details

Summary

Initializes a new instance of the WaitHandle class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

public WaitHandle();

Return to top

Summary

Represents an invalid handle that was passed to a method. This field is read-only.

C# Syntax:

protected static readonly IntPtr InvalidHandle;

Return to top

Summary

Indicates that a WaitHandle.WaitAny operation has timed out before any of the wait handles fire. This field is constant.

C# Syntax:

public const int WaitTimeout;

This field is one of the possible return values of WaitAny.

Return to top

Summary

Gets or sets the native operating system handle.

C# Syntax:

public virtual IntPtr Handle {get; set;}

Exceptions

Exception Type	Condition
SecurityException	The caller does not have the required permission.

SecurityPermissionAttribute for access to unmanaged code. Associated enumeration: SecurityPermissionFlag.UnmanagedCode.

Return to top

Summary

When overridden in a derived class, releases all resources held by the current WaitHandle.

C# Syntax:

public virtual void Close();

This method is the public version of the IDisposable.Dispose method implemented to support the IDisposable interface.

This method releases any unmanaged resources held by the current instance. This method can, but is not required to, suppress finalization during garbage collection by calling the GC.SuppressFinalize method.

Override this method to release resources allocated in derived classes.

Use this method to release all resources held by an instance of WaitHandle. Once this method is called, references to the current instance cause undefined behavior.

Return to top

Inherited
See base class member description: System.MarshalByRefObject.CreateObjRef

Summary

Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.

C# Syntax:

public virtual ObjRef CreateObjRef(    Type requestedType );

requestedType

The Type of the object that the new ObjRef will reference.

Return Value:

Information required to generate a proxy.

Exceptions

Exception Type	Condition
RemotingException	This instance is not a valid remoting object.

Return to top

Summary

When overridden in a derived class, releases the unmanaged resources used by the WaitHandle, and optionally releases the managed resources.

C# Syntax:

protected virtual void Dispose(    bool explicitDisposing );

explicitDisposing

true to release both managed and unmanaged resources; false to release only unmanaged resources.

This method is called by the WaitHandle.Dispose() method and the Finalize method.Dispose() invokes this protected method with the explicitDisposing parameter set to true.Finalize invokes Dispose with explicitDisposing set to false.

When the explicitDisposing parameter is true, this method releases all resources held by any managed objects that this WaitHandle references. This method invokes the Dispose() method of each referenced object.

Dispose can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed in an earlier call to Dispose or Close.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Releases the resources held by the current instance.

C# Syntax:

~WaitHandle();

Application code does not call this method; it is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled. For more information, see GC.SuppressFinalize and Object.Finalize. This method overrides System.Object.Finalize.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.MarshalByRefObject.GetLifetimeService

Summary

Retrieves the current lifetime service object that controls the lifetime policy for this instance.

C# Syntax:

public object GetLifetimeService();

Return Value:

An object of type ILease used to control the lifetime policy for this instance.

For more information about lifetime services, see the LifetimeServices class.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.MarshalByRefObject.InitializeLifetimeService

Summary

Obtains a lifetime service object to control the lifetime policy for this instance.

C# Syntax:

public virtual object InitializeLifetimeService();

Return Value:

An object of type ILease used to control the lifetime policy for this instance. This is the current lifetime service object for this instance if one exists; otherwise, a new lifetime service object initialized to the value of the LifetimeServices.LeaseManagerPollTime property.

For more information about lifetime services, see the LifetimeServices class.

The following code example demonstrates creating a lease.

 public class MyClass : MarshalByRefObject
 {
   public override Object InitializeLifetimeService()
   {
     ILease lease = (ILease)base.InitializeLifetimeService();
     if (lease.CurrentState == LeaseState.Initial)
     {
          lease.InitialLeaseTime = TimeSpan.FromMinutes(1);
          lease.SponsorshipTimeout = TimeSpan.FromMinutes(2);
           lease.RenewOnCallTime = TimeSpan.FromSeconds(2);
     }
       return lease;
   }
 }

    

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Waits for all of the elements in the specified array to receive a signal.

C# Syntax:

public static bool WaitAll(    WaitHandle[] waitHandles );

waitHandles

A WaitHandle array containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object (duplicates).

Return Value:

true when every element in waitHandles has received a signal. If the current thread receives a request to abort before the signals are received, this method returns false.

Exceptions

Exception Type	Condition
ArgumentNullException	The waitHandles parameter is null or one or more of the objects in the waitHandles array are null.
DuplicateWaitObjectException	The waitHandles array contains elements that are duplicates.
NotSupportedException	The number of objects in waitHandles is greater than the system permits.

Returns when the wait terminates, which means either all the handles are signaled or a time out occurs. On some implementations, if more than 64 handles are passed, a NotSupportedException is thrown. If the array contains duplicates, the call will fail.

Return to top

Summary

Waits for all of the elements in the specified array to receive a signal, using an Int32 value to measure the time interval and specifying whether to exit the synchronization domain before the wait.

C# Syntax:

public static bool WaitAll(    WaitHandle[] waitHandles,    int millisecondsTimeout,    bool exitContext );

waitHandles

A WaitHandle array containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object (duplicates).

millisecondsTimeout

The number of milliseconds to wait for the thread to receive a signal.

exitContext

true to exit the synchronization domain for the context before the wait (if in a synchronized context), and reacquire it; otherwise, false.

Return Value:

true to exit the synchronization domain before the wait; otherwise, false.

Exceptions

Exception Type	Condition
ArgumentNullException	The waitHandles parameter is null or one or more of the objects in the waitHandles array is null.
DuplicateWaitObjectException	The waitHandles array contains elements that are duplicates.
NotSupportedException	The number of objects in waitHandles is greater than the system permits.

Returns when the wait terminates, which means either when all the handles are signaled or when time-out occurs. On some implementations, if more than 64 handles are passed, a NotSupportedException is thrown. If there are duplicates in the array, the call will fail.

Return to top

Summary

Waits for all of the elements in the specified array to receive a signal, using a TimeSpan value to measure the time interval and specifying whether to exit the synchronization domain before the wait.

C# Syntax:

public static bool WaitAll(    WaitHandle[] waitHandles,    TimeSpan timeout,    bool exitContext );

waitHandles

A WaitHandle array containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object (duplicates).

timeout

The number of milliseconds to wait for the thread to receive a signal.

exitContext

true to exit the synchronization domain for the context before the wait (if in a synchronized context), and reacquire it; otherwise, false.

Return Value:

true if the method exited the synchronization domain before the wait; otherwise, false.

Exceptions

Exception Type	Condition
ArgumentNullException	The waitHandles parameter is null or one or more of the objects in the waitHandles array is null.
DuplicateWaitObjectException	The waitHandles array contains elements that are duplicates.
NotSupportedException	The number of objects in waitHandles is greater than the system permits.

Returns when the wait terminates, which means either all the handles are signaled or a time out occurs. On some implementations, if more than 64 handles are passed, a NotSupportedException is thrown. If the array contains duplicates, the call will fail.

Return to top

Summary

Waits for any of the elements in the specified array to receive a signal.

C# Syntax:

public static int WaitAny(    WaitHandle[] waitHandles );

waitHandles

A WaitHandle array containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object (duplicates).

Return Value:

The array index of the object that satisfied the wait.

Exceptions

Exception Type	Condition
ArgumentNullException	The waitHandles parameter is null or one or more of the objects in the waitHandles array is null.
DuplicateWaitObjectException	The waitHandles array contains elements that are duplicates.
NotSupportedException	The number of objects in waitHandles is greater than the system permits.

This method returns when the wait terminates, either when any of the handles are signaled or a time out occurrs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. On some implementations, if more that 64 handles are passed, a NotSupportedException is thrown. If the array contains duplicates, the call will fail.

Return to top

Summary

Waits for any of the elements in the specified array to receive a signal, using a 32-bit signed integer to measure the time interval, and specifying whether to exit the synchronization domain before the wait.

C# Syntax:

public static int WaitAny(    WaitHandle[] waitHandles,    int millisecondsTimeout,    bool exitContext );

waitHandles

A WaitHandle array containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object (duplicates).

millisecondsTimeout

The number of milliseconds to wait for the thread to receive a signal.

exitContext

true to exit the synchronization domain for the context before the wait (if in a synchronized context), and reacquire it; otherwise, false.

Return Value:

The array index of the object that satisfied the wait, or WaitHandle.WaitTimeout if no object satisfied the wait and a time interval equivalent to millisecondsTimeout has passed.

Exceptions

Exception Type	Condition
ArgumentNullException	The waitHandles parameter is null or one or more of the objects in the waitHandles array is null.
DuplicateWaitObjectException	The waitHandles array contains elements that are duplicates.
NotSupportedException	The number of objects in waitHandles is greater than the system permits.

This method returns when the wait terminates, either when any of the handles are signaled or when a time out occurrs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. On some implementations, if more that 64 handles are passed, a NotSupportedException is thrown. If the array contains duplicates, the call will fail.

Return to top

Summary

Waits for any of the elements in the specified array to receive a signal, using a TimeSpan to measure the time interval and specifying whether to exit the synchronization domain before the wait.

C# Syntax:

public static int WaitAny(    WaitHandle[] waitHandles,    TimeSpan timeout,    bool exitContext );

waitHandles

A WaitHandle array containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object (duplicates).

timeout

The number of milliseconds to wait for the thread to receive a signal.

exitContext

true to exit the synchronization domain for the context before the wait (if in a synchronized context), and reacquire it; otherwise, false.

Return Value:

The array index of the object that satisfied the wait, or WaitHandle.WaitTimeout if no object satisfied the wait and a time interval equivalent to timeout has passed.

Exceptions

Exception Type	Condition
ArgumentNullException	The waitHandles parameter is null or one or more of the objects in the waitHandles array is null.
DuplicateWaitObjectException	The waitHandles array contains elements that are duplicates.
NotSupportedException	The number of objects in waitHandles is greater than the system permits.

This method returns when the wait terminates, either when any of the handles are signaled or when a time-out occurrs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. On some implementations, if more that 64 handles are passed, a NotSupportedException is thrown. If the array contains duplicates, the call will fail.

Return to top

Summary

When overridden in a derived class, blocks the current thread until the current WaitHandle receives a signal.

C# Syntax:

public virtual bool WaitOne();

Return Value:

true if the current instance receives a signal; otherwise, false.

The caller of this method blocks indefinitely until the current instance receives a signal. Use this method to block until a WaitHandle receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the System.IAsyncResult interface.

Override this method to customize the behavior of derived classes.

Return to top

Summary

When overridden in a derived class, blocks the current thread until the current WaitHandle receives a signal, using 32-bit signed integer to measure the time interval and specifying whether to exit the synchronization domain before the wait.

C# Syntax:

public virtual bool WaitOne(    int millisecondsTimeout,    bool exitContext );

millisecondsTimeout

The number of milliseconds to wait for the thread to receive a signal.

exitContext

true to exit the synchronization domain for the context before the wait (if in a synchronized context), and reacquire it; otherwise, false.

Return Value:

true if the current instance receives a signal; otherwise, false.

The caller of this method blocks indefinitely until the current instance receives a signal. Use this method to block until a WaitHandle receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the System.IAsyncResult interface.

Override this method to customize the behavior of derived classes.

Return to top

Summary

When overridden in a derived class, blocks the current thread until the current instance receives a signal, using a TimeSpan to measure the time interval and specifying whether to exit the synchronization domain before the wait.

C# Syntax:

public virtual bool WaitOne(    TimeSpan timeout,    bool exitContext );

timeout

The number of milliseconds to wait for the thread to receive a signal.

exitContext

true to exit the synchronization domain for the context before the wait (if in a synchronized context), and reacquire it; otherwise, false.

Return Value:

true if the current instance receives a signal; otherwise, false.

The caller of this method blocks indefinitely until the current instance receives a signal. Use this method to block until a WaitHandle receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the System.IAsyncResult interface.

Override this method to customize the behavior of derived classes.

Return to top

Top of page