NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Thread Pool Reference

ThreadPool Reference

Class for posting workitems to the threadpool. There is only one managed thread pool per process.

Restriction

public class ThreadPool
{   
  public static RegisteredWaitHandle RegisterWaitForSingleObject(
        WaitHandle          waitObject,
        WaitOrTimerCallback   callBack,
        Object               state,
        uint            millisecondsTimeOutInterval,
        bool            executeOnlyOnce);

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

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

  public static extern bool QueueUserWorkItem(         
           WaitCallback           callBack,                
         Object                 state
        );

  public static bool QueueUserWorkItem(WaitCallback callBack);
  public static bool BindHandle(int osHandle);
}

RegisterWaitForSingleObject

RegisterWaitForSingleObject. Registers an object so that when the timeout occurs the delegate is called. The RegisterWaitForSingleObject method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs:

Returns the RegisteredWaitHandle object that encapsulates the native handle.

The RegisterWaitForSingleObject method checks the current state of the specified object WaitHandle. If the object's state is nonsignaled, the method registers a wait operation. The wait operation is performed by a thread from the system thread pool. The delegate is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses.

Timeout in milliseconds. A value of –1 indicates no timeout. A value of 0 indicates immediate timeout. If timeOutInterval is not zero and executeOnlyOnce 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. Do not make a blocking RegisteredWaitHandle.Unregister call within the delegate.

The wait thread uses the WaitForMultipleObjects function to monitor registered wait operations. Therefore, if you must use the same native OS 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 object is decreased by one.

The RegisterWaitForSingleObject method can wait for the following objects:

QueueUserWorkItem

QueueUserWorkItem. Queues a user work item to the thread pool. State data can be passed during queuing. By default, the callback function is queued to a non-I/O worker thread.

BindHandle

BindHandle. Bind an OS handle to ThreadPool.

NativeOverlapped Reference

The NativeOverlapped value type has explicit layout that is visible from unmanaged code and will have the same layout as the Win32 OVERLAPPED structure with additional reserved field at the end. The NativeOverlapped NGWS runtime valuetype represents the (unmanaged) Win32 OVERLAPPED structure the layout of this structure must be identical to OVERLAPPED. Two additional dwords are reserved at the end

[structlayout(LayoutKind.Sequential)]
public struct NativeOverlapped
{
  public int   internalLow;
  public int   internalHigh;
  public int   offsetLow;
  public int   offsetHigh;
  public int   eventHandle;
  public int   reservedCOR;
  public int   reservedClasslib; 
}

reservedCOR. Reserved for COR. COR manages this field.

reservedClassLib. Reserved for Class Library data. COR manages this field.

The Win32 OVERLAPPED structure

typedef struct _OVERLAPPED 
{ 
    DWORD  Internal; 
    DWORD  InternalHigh; 
    DWORD  Offset; 
    DWORD  OffsetHigh; 
    HANDLE hEvent; 
} OVERLAPPED;

Overlapped Reference

This class is used to pack and unpack the managed overlapped to and from the native overlapped.

public class Overlapped
{
  public Overlapped() { }

  public Overlapped(int offsetLo, 
                    int offsetHi, int hEvent, IAsyncResult ar);

  public IAsyncResult AsyncResult { get; set }
  public int OffsetLow {get; set}
  public int OffsetHigh {get; set}
  public int EventHandle {get; set}

  public NativeOverlapped* Pack(
                 IOCompletionCallback iocb)
     
  public static Overlapped Unpack(
                 NativeOverlapped* nativeOverlappedPtr)
}

Overlapped. Construct an empty overlapped.

  Overlapped();

Overlapped. Construct an overlapped from the constructor arguments.

Overlapped(int offsetLo, int offsetHi, int hEvent, IAsyncResult ar);

AsyncResult. Property. IAsyncResult interface.

EventHandle. Property. Maps to OVERLAPPED.

OffsetLow. Property. Maps to OVERLAPPED.

OffsetHigh. Property. Maps to OVERLAPPED.

Pack. Packs a managed overlapped class into a NativeOverlapped value type. An unmanaged pointer is returned. This unmanaged pointer can be passed to the OS in overlapped IO operations. The NativeOverlapped value type is fixed in physical memory until Unpack is called.

public NativeOverlapped* Pack(IOCompletionCallback iocb)

Unpack. Unpacks an unmanaged NativeOverlapped value type into a managed overlapped class. The NativeOverlapped value type is freed from physical memory.

public static Overlapped Unpack(NativeOverlapped* nativeOverlappedPtr)

IOCompletionCallback Reference

Delegate that is called when an IO operation completes on the thread pool.

The callback receives the error code, number of bytes and overlapped value type.

public delegate void IOCompletionCallback(
          uint errorCode,           
          uint numBytes,            
          NativeOverlapped* pOVERLAP);   

errorCode. Error code

numBytes. No. of bytes transferred

pOVERLAP. Unmanaged pointer to native oOverlapped value type

WaitCallback Reference

This class is a Delegate which defines the callback method for threadpool user work items. That method must match this delegate.

public delegate void WaitCallback(
                        Object StateObject
                     );

WaitCallback.

WaitOrTimerCallback Reference

Wait or Timer Delegate definition.

public delegate void WaitOrTimerCallback(
                        boolean wasSignalled,
                        Object StateObject
                  );  // signalled or timed out

WaitOrTimerCallback. Receives a boolean parameter which determines whether the handle was signaled or the WaitHandle timed out.