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

[Modules] Component Library/Asynchronous Processor

[top][parent][index]

NAME

       Asynchronous Processor

DESCRIPTION

       The asynchronous processor provides threads for executing queued callbacks.

       The threads in the asynchronous processor wait for callbacks to be queued.

       The asynchronous processor functions operate on a cl_async_proc_t structure
       which should be treated as opaque and manipulated only through the provided
       functions.

SEE ALSO

       Structures:
               cl_async_proc_t, cl_async_proc_item_t

       Initialization:
               cl_async_proc_construct, cl_async_proc_init, cl_async_proc_destroy

       Manipulation:
               cl_async_proc_queue

[Functions] Component Library: Asynchronous Processor/cl_async_proc_construct

[top][index]

NAME

       cl_async_proc_construct

DESCRIPTION

       The cl_async_proc_construct function initializes the state of a
       thread pool.

SYNOPSIS

CL_EXPORT void CL_API
cl_async_proc_construct(
        IN      cl_async_proc_t* const  p_async_proc );

PARAMETERS

       p_async_proc
               [in] Pointer to an asynchronous processor structure.

RETURN VALUE

       This function does not return a value.

NOTES

       Allows calling cl_async_proc_destroy without first calling
       cl_async_proc_init.

       Calling cl_async_proc_construct is a prerequisite to calling any other
       thread pool function except cl_async_proc_init.

SEE ALSO

       Asynchronous Processor, cl_async_proc_init, cl_async_proc_destroy

[Functions] Component Library: Asynchronous Processor/cl_async_proc_destroy

[top][index]

NAME

       cl_async_proc_destroy

DESCRIPTION

       The cl_async_proc_destroy function performs any necessary cleanup
       for a thread pool.

SYNOPSIS

CL_EXPORT void CL_API
cl_async_proc_destroy(
        IN      cl_async_proc_t* const  p_async_proc );

PARAMETERS

       p_async_proc
               [in] Pointer to an asynchronous processor structure to destroy.

RETURN VALUE

       This function does not return a value.

NOTES

       This function blocks until all threads exit, and must therefore not
       be called from any of the asynchronous processor's threads. Because of
       its blocking nature, callers of cl_async_proc_destroy must ensure that
       entering a wait state is valid from the calling thread context.

       This function should only be called after a call to
       cl_async_proc_construct or cl_async_proc_init.

SEE ALSO

       Asynchronous Processor, cl_async_proc_construct, cl_async_proc_init

[Functions] Component Library: Asynchronous Processor/cl_async_proc_init

[top][index]

NAME

       cl_async_proc_init

DESCRIPTION

       The cl_async_proc_init function initialized an asynchronous processor
       for use.

SYNOPSIS

CL_EXPORT cl_status_t CL_API
cl_async_proc_init(
        IN      cl_async_proc_t* const  p_async_proc,
        IN      const uint32_t                  thread_count,
        IN      const char* const               name );

PARAMETERS

       p_async_proc
               [in] Pointer to an asynchronous processor structure to initialize.

       thread_count
               [in] Number of threads to be managed by the asynchronous processor.

       name
               [in] Name to associate with the threads.  The name may be up to 16
               characters, including a terminating null character.  All threads
               created in the asynchronous processor have the same name.

 RETURN VALUES
       CL_SUCCESS if the asynchronous processor creation succeeded.

       CL_INSUFFICIENT_MEMORY if there was not enough memory to inititalize
       the asynchronous processor.

       CL_ERROR if the threads could not be created.

NOTES

       cl_async_proc_init creates and starts the specified number of threads.
       If thread_count is zero, the asynchronous processor creates as many
       threads as there are processors in the system.

SEE ALSO

       Asynchronous Processor, cl_async_proc_construct, cl_async_proc_destroy,
       cl_async_proc_queue

[Structures] Component Library: Asynchronous Processor/cl_async_proc_item_t

[top][index]

NAME

       cl_async_proc_item_t

DESCRIPTION

       Asynchronous processor item structure passed to the cl_async_proc_queue
       function to queue a callback for execution.

SYNOPSIS

typedef struct _cl_async_proc_item
{
        cl_pool_item_t                  pool_item;
        cl_pfn_async_proc_cb_t  pfn_callback;

} cl_async_proc_item_t;

FIELDS

       pool_item
               Pool item for queuing the item to be invoked by the asynchronous
               processor's threads.  This field is defined as a pool item to
               allow items to be managed by a pool.

       pfn_callback
               Pointer to a callback function to invoke when the item is dequeued.

SEE ALSO

       Asynchronous Processor, cl_async_proc_queue, cl_pfn_async_proc_cb_t

[Functions] Component Library: Asynchronous Processor/cl_async_proc_queue

[top][index]

NAME

       cl_async_proc_queue

DESCRIPTION

       The cl_async_proc_queue function queues a callback to an asynchronous
       processor.

SYNOPSIS

CL_EXPORT void CL_API
cl_async_proc_queue(
        IN      cl_async_proc_t* const          p_async_proc,
        IN      cl_async_proc_item_t* const     p_item );

PARAMETERS

       p_async_proc
               [in] Pointer to an asynchronous processor structure to initialize.

       p_item
               [in] Pointer to an asynchronous processor item to queue for execution.
               The callback and context fields of the item must be valid.

 RETURN VALUES
       This function does not return a value.

SEE ALSO

       Asynchronous Processor, cl_async_proc_init, cl_pfn_async_proc_cb_t

[Structures] Component Library: Asynchronous Processor/cl_async_proc_t

[top][index]

NAME

       cl_async_proc_t

DESCRIPTION

       Asynchronous processor structure.

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

SYNOPSIS

typedef struct _cl_async_proc
{
        cl_thread_pool_t        thread_pool;
        cl_qlist_t                      item_queue;
        cl_spinlock_t           lock;
        cl_state_t                      state;

} cl_async_proc_t;

FIELDS

       item_pool
               Pool of items storing the callback function and contexts to be invoked
               by the asynchronous processor's threads.

       thread_pool
               Thread pool that will invoke the callbacks.

       item_queue
               Queue of items that the threads should process.

       lock
               Lock used to synchronize access to the item pool and queue.

SEE ALSO

       Asynchronous Processor

[Definitions] Component Library: Asynchronous Processor/cl_pfn_async_proc_cb_t

[top][index]

NAME

       cl_pfn_async_proc_cb_t

DESCRIPTION

       The cl_pfn_async_proc_cb_t function type defines the prototype for
       callbacks queued to and invoked by the asynchronous processor.

SYNOPSIS

typedef void
(CL_API *cl_pfn_async_proc_cb_t)(
        IN      struct _cl_async_proc_item      *p_item );

PARAMETERS

       p_item
               Pointer to the cl_async_proc_item_t structure that was queued in
               a call to cl_async_proc_queue.

NOTES

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

SEE ALSO

       Asynchronous Processor, cl_async_proc_item_t