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!

Unmanaged Thread Reference

ICorThreadpool interface

The ICorThreadpool interface methods in mscoree.dll can be used through the combination of cortpoolhdr.h, mscoree.h, mscoree.idl, and mscoree.lib

typedef VOID (__stdcall *WAITORTIMERCALLBACK)(PVOID, BOOL); 

interface ICorThreadpool : IUnknown
{
  //. . . 
  HRESULT CorRegisterWaitForSingleObject(
                     [in] HANDLE* phNewWaitObject,
                     [in] HANDLE hWaitObject,
                     [in] WAITORTIMERCALLBACK Callback,
                     [in] PVOID Context,
                     [in] ULONG timeout,
                     [in] BOOL  executeOnlyOnce,
                     [out] BOOL* result  );

  HRESULT CorUnregisterWait(
                     [in] HANDLE hWaitObject,
                     [in] HANDLE CompletionEvent,
                     [out] BOOL* result);

  HRESULT CorQueueUserWorkItem(
                     [in] LPTHREAD_START_ROUTINE Function,
                     [in] PVOID Context,
                     [in] BOOL executeOnlyOnce,
                     [out] BOOL* result );

  HRESULT CorCreateTimer(
                      [in] HANDLE* phNewTimer,
                      [in] WAITORTIMERCALLBACK Callback,
                      [in] PVOID Parameter,
                      [in] DWORD DueTime,
                      [in] DWORD Period,
                      [out] BOOL* result);

  HRESULT CorChangeTimer(
                      [in] HANDLE Timer,
                      [in] ULONG DueTime,
                      [in] ULONG Period,
                      [out] BOOL* result);

  HRESULT CorDeleteTimer(
                      [in] HANDLE Timer,
                      [in] HANDLE CompletionEvent,
                      [out] BOOL* result);

  HRESULT CorBindIoCompletionCallback(
                      [in] HANDLE fileHandle,
                      [in] LPOVERLAPPED_COMPLETION_ROUTINE callback); 
  // . . .
}

CorQueueUserWorkItem

The CorQueueUserWorkItem function queues a work item to a worker thread in the thread pool.

CorRegisterWaitForSingleObject

The CorRegisterWaitForSingleObject function queues the specified callback function to the thread pool. A worker thread will execute the function when one of the following occurs:

The CorRegisterWaitForSingleObject function checks the current state of the specified object. If the object's state is nonsignaled, the function registers a wait operation. The wait operation is performed by a thread from the thread pool. The callback routine is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses.

To cancel the wait operation, call the CorUnregisterWait function. Do not make a blocking CorUnregisterWait call within the callback function.

Internally the wait thread use WaitForMultipleObjects to monitor registered wait operations. Therefore, if you must use the same handle in multiple calls to CorRegisterWaitForSingleObject, you must duplicate the handle using the DuplicateHandle function. Note that you should not pulse an event object passed to CorRegisterWaitForSingleObject, 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 CorRegisterWaitForSingleObject function can wait for the following objects:

CorUnregisterWait

The CorUnregisterWait function cancels a registered wait operation issued by the CorRegisterWaitForSingleObject function.

If the wait thread is executing the callback function, you can call CorUnregisterWait inside the callback function. If a worker thread is executing the callback function, do not call CorUnregisterWait inside the callback function.

If CompletionEvent is not NULL or –1, no new callback functions can be executed. However, there may be callback functions already queued to worker threads whose execution has not started.

CorCreateTimer

The CorCreateTimer function creates a timer. This timer expires at the specified due time, then after every specified period. When the timer expires, the callback function is called.

If the DueTime and Period parameters are both nonzero, the timer will be signaled first at the due time, then periodically.

To cancel a timer, call the CorDeleteTimer function.

CorDeleteTimer

The CorDeleteTimer function cancels a timer.

You can set CompletionEvent to –1 when calling this function from within the timer callback of another timer as long as the callback function is not executed in the timer thread. However, a deadlock may occur if two callback functions attempt a blocking CorDeleteTimer call on each others' timers.

CorChangeTimer

The CorChangeTimer function updates a timer that was created by the CorCreateTimer function.

You can call CorChangeTimer in a timer callback.

If you call CorChangeTimer on a one-shot timer (it's period is zero) that has already expired, the timer is not updated.

Do not call CorChangeTimer after calling CorDeleteTimer on a handle.

CorBindIOCompletionCallback

The CorBindIOCompletionCallback allows users associate an OS handle with the thread pool and specify a completion callback. When async IO operations complete on the OS handle the callback is called.

osHandle. The OS handle to bind to the IO completion port.

callback. The callback to be called when an async operation completes on the IO completion port.



LPOVERLAPPED_COMPLETETION_ROUTINE has the following signature:

VOID OVERLAPPED_COMPLETETION_ROUTINE(
     DWORD dwErrorCode,                // completion code
     DWORD dwNumberOfBytesTransfered,  // number of bytes transferred
     LPOVERLAPPED lpOverlapped         // I/O information buffer
   );