TABLE OF CONTENTS

1. Component Library/System Callback
2. Component Library: System Callback/cl_is_sys_callback_inited
3. Component Library: System Callback/cl_pfn_sys_callback_t
4. Component Library: System Callback/cl_sys_callback_get
5. Component Library: System Callback/cl_sys_callback_put
6. Component Library: System Callback/cl_sys_callback_queue

Component Library/System Callback

    System Callback

    The System Callback provider uses threads from a system thread-pool to 
    invoke specified callback functions.

    Callbacks can be queued in a low- or high-priority queue for processing.

    cl_thread_suspend and cl_thread_stall can be used to delay or stall the 
    callback thread.

    Environments that do not have a native system thread-pool emulate this 
    functionality to provide cross-environment support.

    The cl_sys_callback_item_t structure should be treated as opaque and be
    manipulated only through the provided functions.

Component Library: System Callback/cl_is_sys_callback_inited

    cl_is_sys_callback_inited

    The cl_is_sys_callback_inited function returns whether the system 
    callback provider was initialized successfully

boolean_t
__cl_is_sys_callback_inited( void );

    TRUE if the system callback provider was initialized successfully.

    FALSE otherwise.

    Allows checking the state of the system callback provider to determine 
    if invoking member functions is appropriate.

    System Callback

Component Library: System Callback/cl_pfn_sys_callback_t

    cl_pfn_sys_callback_t

    The cl_pfn_sys_callback_t function type defines the prototype for 
    functions invoked by the system callback provider.

typedef void 
(*cl_pfn_sys_callback_t)( 
    IN  void*   get_context, 
    IN  void*   queue_context );

    get_context 
        [in] Value of the get_context parameter specified in a call 
        to cl_sys_callback_get. 

    queue_context 
        [in] Value of the queue_context parameter specified in a call 
        to cl_sys_callback_queue.

    This function does not return a value.

    This function type is provided as function prototype reference for 
    the function provided by users as a parameter to the 
    cl_sys_callback_queue function.

    System Callback, cl_sys_callback_queue

Component Library: System Callback/cl_sys_callback_get

    cl_sys_callback_get

    The cl_sys_callback_get function retrieves a system callback item.

cl_sys_callback_item_t*
cl_sys_callback_get( 
    IN  const void* const get_context );

    get_context 
        [in] Context value to pass into the callback function.

    Returns a pointer to a system callback item if successful.

    Returns NULL if the call fails.

    A system callback item must be released with a call to cl_sys_callback_put.

    Care must be taken to prevent a system callback item from being returned 
    to the pool while it is queued. Callers of cl_sys_callback_queue must not 
    return the system callback item to the pool until their callback has been 
    invoked.

    In Windows 2000 Kernel Mode, the get_context is a pointer to the device 
    object for which the system callback is being used.

    System Callback, SysCallbackPut, SysCallbackQueue 

Component Library: System Callback/cl_sys_callback_put

    cl_sys_callback_put

    The cl_sys_callback_put function releases the specified 
    system callback item.

void
cl_sys_callback_put( 
    IN  cl_sys_callback_item_t* const   p_item );

    p_item 
        [in] Pointer to a system callback item to release.

    This function does not return a value.

    The p_item parameter points to a system callback item returned by 
    a previous call to cl_sys_callback_get.

    The specified system callback item must not be queued when making
    a call to this function.  This function can, however, be called
    from the callback function.

    System Callback, cl_sys_callback_get, cl_sys_callback_queue 

Component Library: System Callback/cl_sys_callback_queue

    cl_sys_callback_queue

    The cl_sys_callback_queue function queues the specified system callback item 
    for execution.

cl_status_t
cl_sys_callback_queue( 
    IN  cl_sys_callback_item_t* const   p_item, 
    IN  cl_pfn_sys_callback_t           pfn_callback,
    IN  const void* const               queue_context, 
    IN  const boolean_t                 high_priority );

    p_item 
        [in] Pointer to a system callback item. 

    pfn_callback 
        [in] Pointer to a function to be invoked by the system callback module.
        See the cl_pfn_sys_callback_t function type definition for details
        about the callback function. 

    queue_context 
        [in] Value passed to the system callback function. 

    high_priority 
        [in] Specifies whether the request should be queued in the high- or 
        low-priority queue.

    CL_SUCCESS if the system callback item was successfully queued.

    CL_ERROR otherwise.

    A thread from the system thread pool will invoke the specified callback
    function with the get_context value specified in the call to 
    cl_sys_callback_get and the specified context as parameters.

    The high priority queue is processed before the low priority queue. There 
    is no fairness algorithm implemented for removing items from the queues.

    Care should be taken to only queue a given system callback item once 
    at a time.

    System Callback, cl_sys_callback_get, cl_pfn_sys_callback_t