System.Threading.ThreadPool Class

Summary

Provides a pool of threads that can be used to post work items, process asynchronous I/O, wait on behalf of other threads, and process timers.

C# Syntax:

public sealed class ThreadPool

Many applications create threads that spend a great deal of time in the sleeping state, waiting for an event to occur. Other threads may enter a sleeping state only to be awakened periodically to poll for a change or update status information. Thread pooling enables you to use threads more efficiently by providing your application with a pool of worker threads that are managed by the system. One thread monitors the status of several wait operations queued to the thread pool. When a wait operation completes, a worker thread from the thread pool executes the corresponding callback function.

You can also queue work items that are not related to a wait operation to the thread pool. To request that a work item be handled by a thread in the thread pool, call the ThreadPool.QueueUserWorkItem method. This method takes as a parameter a reference to the method or delegate that will be called by the thread selected from the thread pool. There is no way to cancel a work item after it has been queued.

Timer-queue timers and registered wait operations also use the thread pool. Their callback functions are queued to the thread pool.

The thread pool is created the first time you create an instance of the ThreadPool class. The thread pool has a default limit of 25 threads per available processor, which could be changed using CorSetMaxThreads as defined in the mscoree.h file. Each thread uses the default stack size and runs at the default priority. Each process can have only one operating system thread pool.

System.Threading Namespace

System.Threading.ThreadPool Member List:

Public Methods

Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetAvailableThreads	Retrieves the number of thread pool requests or work items that the user can add before reaching the maximum limit defined in ThreadPool.GetMaxThreads.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetMaxThreads	Retrieves the number of requests to the thread pool that can queue concurrently. All requests above that number are blocked until some of the queued requests finish work.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
QueueUserWorkItem	Overloaded: QueueUserWorkItem(WaitCallback callBack) Queues a user work item to the thread pool and invokes the specified delegate.
QueueUserWorkItem	Overloaded: QueueUserWorkItem(WaitCallback callBack, object state) Queues a user work item to the thread pool, invokes the specified delegate, and specifies an object to be passed to the delegate when serviced from the thread pool.
RegisterWaitForSingleObject	Overloaded: RegisterWaitForSingleObject(WaitHandle waitObject, WaitOrTimerCallback callBack, object state, int millisecondsTimeOutInterval, bool executeOnlyOnce) Registers a delegate that is waiting for a WaitHandle, using a 32-bit signed integer for the time out in milliseconds.
RegisterWaitForSingleObject	Overloaded: RegisterWaitForSingleObject(WaitHandle waitObject, WaitOrTimerCallback callBack, object state, long millisecondsTimeOutInterval, bool executeOnlyOnce) Registers a delegate that is waiting for a WaitHandle, using a 32-bit unsigned integer for the time out in milliseconds.
RegisterWaitForSingleObject	Overloaded: RegisterWaitForSingleObject(WaitHandle waitObject, WaitOrTimerCallback callBack, object state, TimeSpan timeout, bool executeOnlyOnce) Registers a delegate that is waiting for a WaitHandle, using a TimeSpan value for the time out.
RegisterWaitForSingleObject	Overloaded: RegisterWaitForSingleObject(WaitHandle waitObject, WaitOrTimerCallback callBack, object state, uint millisecondsTimeOutInterval, bool executeOnlyOnce) Registers a delegate that is waiting for a WaitHandle, using a 32-bit unsigned integer for the time out in milliseconds.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.
UnsafeQueueUserWorkItem	Queues a user work item to the thread pool.
UnsafeRegisterWaitForSingleObject	Overloaded: UnsafeRegisterWaitForSingleObject(WaitHandle waitObject, WaitOrTimerCallback callBack, object state, int millisecondsTimeOutInterval, bool executeOnlyOnce) Queues the specified delegate to the thread pool.
UnsafeRegisterWaitForSingleObject	Overloaded: UnsafeRegisterWaitForSingleObject(WaitHandle waitObject, WaitOrTimerCallback callBack, object state, long millisecondsTimeOutInterval, bool executeOnlyOnce) Queues the specified delegate to the thread pool.
UnsafeRegisterWaitForSingleObject	Overloaded: UnsafeRegisterWaitForSingleObject(WaitHandle waitObject, WaitOrTimerCallback callBack, object state, TimeSpan timeout, bool executeOnlyOnce) Queues the specified delegate to the thread pool.
UnsafeRegisterWaitForSingleObject	Overloaded: UnsafeRegisterWaitForSingleObject(WaitHandle waitObject, WaitOrTimerCallback callBack, object state, uint millisecondsTimeOutInterval, bool executeOnlyOnce) Queues the specified delegate to the thread pool.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
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.Threading.ThreadPool

System.Threading.ThreadPool Member Details

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

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

C# Syntax:

~ThreadPool();

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

Return to top

Summary

Retrieves the number of thread pool requests or work items that the user can add before reaching the maximum limit defined in ThreadPool.GetMaxThreads.

C# Syntax:

public static void GetAvailableThreads(    out int workerThreads,    out int completionPortThreads );

workerThreads

The number of worker threads.

completionPortThreads

The number of asynchronous I/O threads.

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

Summary

Retrieves the number of requests to the thread pool that can queue concurrently. All requests above that number are blocked until some of the queued requests finish work.

C# Syntax:

public static void GetMaxThreads(    out int workerThreads,    out int completionPortThreads );

workerThreads

The number of worker threads.

completionPortThreads

The number of asynchronous I/O threads.

When a call to GetMaxThreads completes the workerThreads contains the maximum number of worker threads and the completionPortThreads parameter contains the maximum number of asynchronous I/O threads.

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.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

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

Return to top

Summary

Queues a user work item to the thread pool and invokes the specified delegate.

C# Syntax:

public static bool QueueUserWorkItem(    WaitCallback callBack );

callBack

A WaitCallback representing the delegate to invoke when the thread in the thread pool picks up the work item.

Return Value:

true if the method succeeds; otherwise, false.

State data can be stored in the instance fields of the class on which the delegate is defined. The callback function is queued to a worker thread.

Return to top

Summary

Queues a user work item to the thread pool, invokes the specified delegate, and specifies an object to be passed to the delegate when serviced from the thread pool.

C# Syntax:

public static bool QueueUserWorkItem(    WaitCallback callBack,    object state );

callBack

A WaitCallback representing the delegate to invoke when a thread in the thread pool picks up the work item.

state

The object that is passed to the delegate when serviced from the thread pool.

Return Value:

true if the method succeeds; otherwise, false.

State data can be stored in the instance fields of the class on which the delegate is defined. The callback function is queued to a worker thread.

Return to top

Summary

Registers a delegate that is waiting for a WaitHandle, using a 32-bit signed integer for the time out in milliseconds.

C# Syntax:

public static RegisteredWaitHandle RegisterWaitForSingleObject(    WaitHandle waitObject,    WaitOrTimerCallback callBack,    object state,    int millisecondsTimeOutInterval,    bool executeOnlyOnce );

waitObject

The WaitHandle to register.

callBack

The WaitOrTimerCallback delegate to call when the waitObject parameter is signaled.

state

The object passed to the delegate.

millisecondsTimeOutInterval

The time out in milliseconds. If the millisecondsTimeOutInterval parameter is zero (0), the function tests the object's state and returns immediately. If millisecondsTimeOutInterval is -1, the function's time-out interval never elapses.

executeOnlyOnce

true to indicate the thread will no longer wait on the waitObject parameter after the delegate has been called; false to indicate the timer is reset every time the wait operation completes until the wait is unregistered.

Return Value:

The RegisteredWaitHandle that encapsulates the native handle.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The millisecondsTimeOutInterval parameter is less than -1.

Return to top

Summary

Registers a delegate that is waiting for a WaitHandle, using a 32-bit unsigned integer for the time out in milliseconds.

C# Syntax:

public static RegisteredWaitHandle RegisterWaitForSingleObject(    WaitHandle waitObject,    WaitOrTimerCallback callBack,    object state,    long millisecondsTimeOutInterval,    bool executeOnlyOnce );

waitObject

The WaitHandle to register.

callBack

The WaitOrTimerCallback delegate to call when the waitObject parameter is signaled.

state

The object passed to the delegate.

millisecondsTimeOutInterval

The time out in milliseconds. If the millisecondsTimeOutInterval parameter is zero (0), the function tests the object's state and returns immediately. If millisecondsTimeOutInterval is -1, the function's time-out interval never elapses.

executeOnlyOnce

true to indicate the thread will no longer wait on the waitObject parameter after the delegate has been called; false to indicate the timer is reset every time the wait operation completes until the wait is unregistered.

Return Value:

The RegisteredWaitHandle that encapsulates the native handle.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The millisecondsTimeOutInterval parameter is less than -1.

Return to top

Summary

Registers a delegate that is waiting for a WaitHandle, using a TimeSpan value for the time out.

C# Syntax:

public static RegisteredWaitHandle RegisterWaitForSingleObject(    WaitHandle waitObject,    WaitOrTimerCallback callBack,    object state,    TimeSpan timeout,    bool executeOnlyOnce );

waitObject

The WaitHandle to register.

callBack

The WaitOrTimerCallback delegate to call when the waitObject parameter is signaled.

state

The object passed to the delegate.

timeout

The time out represented by a TimeSpan. If timeout is zero, the function tests the object's state and returns immediately. If timeout is -1, the function's time-out interval never elapses.

executeOnlyOnce

true to indicate the thread will no longer wait on the waitObject parameter after the delegate has been called; false to indicate the timer is reset every time the wait operation completes until the wait is unregistered.

Return Value:

The RegisteredWaitHandle that encapsulates the native handle.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The timeout parameter is less than -1.
NotSupportedException	The timeout parameter is greater than Int32.MaxValue.

Return to top

Summary

Registers a delegate that is waiting for a WaitHandle, using a 32-bit unsigned integer for the time out in milliseconds.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public static RegisteredWaitHandle RegisterWaitForSingleObject(    WaitHandle waitObject,    WaitOrTimerCallback callBack,    object state,    uint millisecondsTimeOutInterval,    bool executeOnlyOnce );

waitObject

The WaitHandle to register.

callBack

The WaitOrTimerCallback delegate to call when the waitObject parameter is signaled.

state

The object passed to the delegate.

millisecondsTimeOutInterval

The time out in milliseconds. If the millisecondsTimeOutInterval parameter is zero (0), the function tests the object's state and returns immediately. If millisecondsTimeOutInterval is -1, the function's time-out interval never elapses.

executeOnlyOnce

true to indicate the thread will no longer wait on the waitObject parameter after the delegate has been called; false to indicate the timer is reset every time the wait operation completes until the wait is unregistered.

Return Value:

The RegisteredWaitHandle that can be used to cancel the registered wait operation.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The millisecondsTimeOutInterval parameter is less than -1.

The RegisterWaitForSingleObject method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs:

• The specified object is in the signaled state.
• The time-out interval elapses.

The RegisterWaitForSingleObject method checks the current state of the specified object's WaitHandle. If the object's state is non-signaled, the method registers a wait operation. The wait operation is performed by a thread from the thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If the timeOutInterval parameter is not zero (0) and the executeOnlyOnce parameter is not false, the timer is reset every time the event is signaled or the time-out interval elapses.

To cancel the wait operation, call the RegisteredWaitHandle.Unregister method.

The wait thread uses the WaitForMultipleObjects function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to RegisterWaitForSingleObject, you must duplicate the handle using the Win32 DuplicateHandle function. Note that you should not pulse an event object passed to RegisterWaitForSingleObject, because the wait thread might not detect that the event is signaled before it is reset.

Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one.

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

Queues a user work item to the thread pool.

C# Syntax:

public static bool UnsafeQueueUserWorkItem(    WaitCallback callBack,    object state );

callBack

A WaitCallback representing the delegate to invoke when a thread in the thread pool picks up the work item.

state

The object that is passed to the delegate when serviced from the thread pool.

Return Value:

true if the method succeeds; otherwise, false.

Exceptions

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

This is an unsafe version of ThreadPool.QueueUserWorkItem that does not propagate the calling stack onto the worker thread. This allows code to lose the calling stack and thereby elevate its security privileges.

SecurityPermission to provide evidence and view and modify policy. Associated enumerations: SecurityPermissionFlag.ControlEvidence, SecurityPermissionFlag.ControlPolicy.

Return to top

Summary

Queues the specified delegate to the thread pool.

C# Syntax:

public static RegisteredWaitHandle UnsafeRegisterWaitForSingleObject(    WaitHandle waitObject,    WaitOrTimerCallback callBack,    object state,    int millisecondsTimeOutInterval,    bool executeOnlyOnce );

waitObject

The WaitHandle to register.

callBack

The delegate to call when the waitObject parameter is signaled.

state

The object that is passed to the delegate.

millisecondsTimeOutInterval

The time out in milliseconds. If the millisecondsTimeOutInterval parameter is zero (0), the function tests the object's state and returns immediately. If millisecondsTimeOutInterval is -1, the function's time-out interval never elapses.

executeOnlyOnce

true to indicate the thread will no longer wait on the waitObject parameter after the delegate has been called; false to indicate the timer is reset every time the wait operation completes until the wait is unregistered.

Return Value:

The RegisteredWaitHandle object that can be used to cancel the registered wait operation.

Exceptions

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

This is an unsafe version of ThreadPool.RegisterWaitForSingleObject that does not propagate the calling stack onto the worker thread. This allows code to lose the calling stack and thereby elevate its security privileges.

SecurityPermission to provide evidence and view and modify policy. Associated enumerations: SecurityPermissionFlag.ControlEvidence, SecurityPermissionFlag.ControlPolicy.

Return to top

Summary

Queues the specified delegate to the thread pool.

C# Syntax:

public static RegisteredWaitHandle UnsafeRegisterWaitForSingleObject(    WaitHandle waitObject,    WaitOrTimerCallback callBack,    object state,    long millisecondsTimeOutInterval,    bool executeOnlyOnce );

waitObject

The WaitHandle to register.

callBack

The delegate to call when the waitObject parameter is signaled.

state

The object that is passed to the delegate.

millisecondsTimeOutInterval

The time out in milliseconds. If the millisecondsTimeOutInterval parameter is zero (0), the function tests the object's state and returns immediately. If millisecondsTimeOutInterval is -1, the function's time-out interval never elapses.

executeOnlyOnce

true to indicate the thread will no longer wait on the waitObject parameter after the delegate has been called; false to indicate the timer is reset every time the wait operation completes until the wait is unregistered.

Return Value:

The RegisteredWaitHandle object that can be used to cancel the registered wait operation.

Exceptions

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

This is an unsafe version of ThreadPool.RegisterWaitForSingleObject that does not propagate the calling stack onto the worker thread. This allows code to lose the calling stack and thereby elevate its security privileges.

SecurityPermission to provide evidence and view and modify policy. Associated enumerations: SecurityPermissionFlag.ControlEvidence, SecurityPermissionFlag.ControlPolicy.

Return to top

Summary

Queues the specified delegate to the thread pool.

C# Syntax:

public static RegisteredWaitHandle UnsafeRegisterWaitForSingleObject(    WaitHandle waitObject,    WaitOrTimerCallback callBack,    object state,    TimeSpan timeout,    bool executeOnlyOnce );

waitObject

The WaitHandle to register.

callBack

The delegate to call when the waitObject parameter is signaled.

state

The object that is passed to the delegate.

timeout

The time out represented by a TimeSpan. If timeout is zero, the function tests the object's state and returns immediately. If timeout is -1, the function's time-out interval never elapses.

executeOnlyOnce

true to indicate the thread will no longer wait on the waitObject parameter after the delegate has been called; false to indicate the timer is reset every time the wait operation completes until the wait is unregistered.

Return Value:

The RegisteredWaitHandle object that can be used to cancel the registered wait operation.

Exceptions

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

This is an unsafe version of ThreadPool.RegisterWaitForSingleObject that does not propagate the calling stack onto the worker thread. This allows code to lose the calling stack and thereby elevate its security privileges.

SecurityPermission to provide evidence and view and modify policy. Associated enumerations: SecurityPermissionFlag.ControlEvidence, SecurityPermissionFlag.ControlPolicy.

Return to top

Summary

Queues the specified delegate to the thread pool.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public static RegisteredWaitHandle UnsafeRegisterWaitForSingleObject(    WaitHandle waitObject,    WaitOrTimerCallback callBack,    object state,    uint millisecondsTimeOutInterval,    bool executeOnlyOnce );

waitObject

The WaitHandle to register.

callBack

The delegate to call when the waitObject parameter is signaled.

state

The object that is passed to the delegate.

millisecondsTimeOutInterval

The time out in milliseconds. If the millisecondsTimeOutInterval parameter is zero (0), the function tests the object's state and returns immediately. If millisecondsTimeOutInterval is -1, the function's time-out interval never elapses.

executeOnlyOnce

true to indicate the thread will no longer wait on the waitObject parameter after the delegate has been called; false to indicate the timer is reset every time the wait operation completes until the wait is unregistered.

Return Value:

The RegisteredWaitHandle object that can be used to cancel the registered wait operation.

Exceptions

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

This is an unsafe version of ThreadPool.RegisterWaitForSingleObject that does not propagate the calling stack onto the worker thread. This allows code to lose the calling stack and thereby elevate its security privileges.

SecurityPermission to provide evidence and view and modify policy. Associated enumerations: SecurityPermissionFlag.ControlEvidence, SecurityPermissionFlag.ControlPolicy.

Return to top

Top of page