Shared Source CLI Essentials

Asynchronous Procedure Calls

Asynchronous Procedure Calls (APCs ), which provide a way to execute code within the context of a specific thread, are used by Rotor’s threading implementation. (Specifically, they provide a way to politely interrupt threads that are busily beavering away at something else.) They are implemented as callback functions, which always have the signature:

    VOID CALLBACK APCProc(ULONG_PTR dwParam);

An APC is queued to a thread, where it is scheduled for execution. While not strictly a synchronization mechanism, the queuing of an APC has an effect similar to synchronization.

The QueueUserAPC API adds the APC passed as a parameter to a per-thread queue of functions to be called. A thread will call its APCs only when it is alertable, which is defined to be after it uses WaitForMultipleObjectsEx or SleepEx with the alertable parameter set to True. APCs are called in FIFO order.

In the Unix PAL, the thread maintains its queue as a singly linked list of APC_TRACKER structures:

    typedef struct _APC_TRACKER
    {
      PAPCFUNC             pfnAPC;
      ULONG_PTR            pAPCData;
      struct _APC_TRACKER *pNext;
    } APC_TRACKER, *LPAPC_TRACKER;

The root of this list can be found in the lpAPCTracker field of THREAD.

Since each APCProc takes a ULONG_PTR argument, each element of the APC tracker list must hold onto the function argument in addition to the function pointer. The routine THREADCallThreadAPCs handles the calling of the APC functions and is called in three places: before the thread starts actually waiting ...