Exploring the ThreadPool Class

Exploring the ThreadPool Class

In this section, we will be exploring the various aspects of the ThreadPool class and will see how they can be employed to create thread pools in our .NET applications. The ThreadPool class provides a pool of threads that can be used to do the following things:

Process work items

Process asynchronous I/O calls

Process timers

Wait on behalf of other threads

The following table gives the list of methods of the ThreadPool class and their functionality.

Of the above methods, QueueUserWorkItem() and RegisterWaitForSingleObject() play the most important roles in thread pooling. Let's dig into the details of each method. Here we'll see both their syntax and a sample call in C#:

The BindHandle() method binds an operating system handle to the thread pool. It's a way to call BindIoCompletionCallback; Several classes in the BCL - such as Socket and FileStream - use it internally to bind their handles to an I/O completion port of the CLR-created thread-pool. The client application usually doesn't need to call this method directly; this functionality is indirectly accessed when methods such as BeginRead or BeginReceive are called.

public static bool BindHandle(IntPtr osHandle);

osHandle refers to the IntPtr type holding the OS handle. The return value is a Boolean where true indicates binding to the handle. This method throws a SecurityException if the caller does not have the required permission.

The GetAvailableThreads() method indicates the number of thread pool requests that can be added before reaching the maximum specified limit:

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

workerThreads refers to the number of worker threads of the thread pool while completionPortThreads refers to the number of asynchronous I/O threads.

The GetMaxThreads() method returns the maximum number of concurrent requests that a thread pool can handle. Any requests above this limit are queued until some of the threads in the thread pool are freed up:

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

workerThreads refers to the number of worker threads of the thread pool while the completionPortThreads refers to the number of asynchronous I/O threads.

QueueUserWorkItem() is an overloaded method that queues a work item to the thread pool. It may be called in the following two forms. In the first case, the method queues the specified work item to the thread pool and calls the specified delegate associated with it. This case has the following syntax:

public static bool QueueUserWorkItem(WaitCallback callBack);

Here callBack refers to the delegate to be invoked when the thread in the thread pool takes the work item. The return value true indicates the method succeeded and false indicates failure.

In the second case, the method queues the specified work item to the thread pool, invokes the specified delegate, and specifies the object to be passed to the delegate when the work item is executed in the pool. In this case the method call has the following syntax:

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

callBack refers to the delegate to be invoked when the thread in the thread pool services the work item, while state refers to the object containing the state that is being passed to the delegate when the servicing of the work item occurs. The return value true indicates the method succeeded and fFalse indicates failure.

RegisterWaitForSingleObject() is also an overloaded method. It registers a delegate that waits for a WaitHandle. This class encapsulates all the objects of the operating system that wait for exclusive access to shared resources.

The method takes the following four forms. In the first case, the method registers a delegate and waits for the WaitHandle indicated by the timeout in milliseconds, which is given by a 32-bit signed integer. This overloaded form of the method has the following syntax in C#:

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

In the above syntax, the waitObject refers to the WaitHandle and the callBack refers to the WaitOrTimerCallback delegate to be invoked. The state parameter refers to the Object to be passed to the delegate. The millisecondsTimeOutInterval parameter refers to the timeout in milliseconds; if its value is then the function tests the object state and returns immediately, on the other hand if its value is the function waits forever. The executeOnlyOnce parameter indicates whether the thread has to wait on the waitObject parameter after the delegate has been invoked or not. The RegisteredWaitHandle parameter encapsulates the native handle.

This method throws an ArgumentOutOfRangeException if the millisecondsTimeOutInterval parameter is less than .

In the second case, the method does the same thing as specified in the first case but waits for the WaitHandle indicated by a timeout in milliseconds that is given by a 32-bit unsigned integer. This overloaded form of the method has the following syntax:

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

In the third case, the method waits for the WaitHandle indicated by the timeout given by the TimeSpan value. This overloaded form of the method has the following syntax:

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

In the fourth case, the timeout is given in milliseconds by an unsigned integer and because unsigned integers are not part of the common type system, this method is not CLS compliant:

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

The UnsafeQueueUserWorkItem() method is the unsafe version of the QueueUserWorkItem() method. It is unsafe because it does not propagate the calling stack to the worker thread, which means that the code can lose the calling stack and, in doing so, gain security privileges it should not be able to. It has the following syntax:

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

The UnsafeRegisterWaitForSingleObject() method is the unsafe version of the RegisterWaitForSingleObject() method and takes the following four forms:

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

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

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

These unsafe methods should not be used when queuing work items from code you don't fully trust, and in general should not normally be used.