Generated from ./inc/complib/cl_syscallback.h with ROBODoc v4.99.17 on Sun Mar 04 2007 18:17:51

[Modules] Component Library/System Callback

[top][parent][index]

NAME

       System Callback

DESCRIPTION

       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.

[Functions] Component Library: System Callback/cl_is_sys_callback_inited

[top][index]

NAME

       cl_is_sys_callback_inited

DESCRIPTION

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

SYNOPSIS

boolean_t
__cl_is_sys_callback_inited( void );
/*
* RETURN VALUES
*       TRUE if the system callback provider was initialized successfully.
*
*       FALSE otherwise.

NOTES

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

SEE ALSO

       System Callback

[Definitions] Component Library: System Callback/cl_pfn_sys_callback_t

[top][index]

NAME

       cl_pfn_sys_callback_t

DESCRIPTION

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

SYNOPSIS

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

PARAMETERS

       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.

RETURN VALUE

       This function does not return a value.

NOTES

       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.

SEE ALSO

       System Callback, cl_sys_callback_queue

[Functions] Component Library: System Callback/cl_sys_callback_get

[top][index]

NAME

       cl_sys_callback_get

DESCRIPTION

       The cl_sys_callback_get function retrieves a system callback item.

SYNOPSIS

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

PARAMETERS

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

 RETURN VALUES
       Returns a pointer to a system callback item if successful.

       Returns NULL if the call fails.

NOTES

       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.

SEE ALSO

       System Callback, SysCallbackPut, SysCallbackQueue

[Functions] Component Library: System Callback/cl_sys_callback_put

[top][index]

NAME

       cl_sys_callback_put

DESCRIPTION

       The cl_sys_callback_put function releases the specified
       system callback item.

SYNOPSIS

CL_EXPORT void CL_API
cl_sys_callback_put(
        IN      cl_sys_callback_item_t* const   p_item );

PARAMETERS

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

RETURN VALUE

       This function does not return a value.

NOTES

       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.

SEE ALSO

       System Callback, cl_sys_callback_get, cl_sys_callback_queue

[Functions] Component Library: System Callback/cl_sys_callback_queue

[top][index]

NAME

       cl_sys_callback_queue

DESCRIPTION

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

SYNOPSIS

CL_EXPORT cl_status_t CL_API
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 );

PARAMETERS

       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.

 RETURN VALUES
       CL_SUCCESS if the system callback item was successfully queued.

       CL_ERROR otherwise.

NOTES

       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.

SEE ALSO

       System Callback, cl_sys_callback_get, cl_pfn_sys_callback_t