TABLE OF CONTENTS

1. Component Library/Asynchronous Processor
2. Component Library: Asynchronous Processor/cl_async_proc_construct
3. Component Library: Asynchronous Processor/cl_async_proc_destroy
4. Component Library: Asynchronous Processor/cl_async_proc_init
5. Component Library: Asynchronous Processor/cl_async_proc_item_t
6. Component Library: Asynchronous Processor/cl_async_proc_queue
7. Component Library: Asynchronous Processor/cl_async_proc_t
8. Component Library: Asynchronous Processor/cl_pfn_async_proc_cb_t

Component Library/Asynchronous Processor

    Asynchronous Processor

    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.

    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

Component Library: Asynchronous Processor/cl_async_proc_construct

    cl_async_proc_construct

    The cl_async_proc_construct function initializes the state of a
    thread pool.

void
cl_async_proc_construct(
    IN  cl_async_proc_t* const  p_async_proc );

    p_async_proc
        [in] Pointer to an asynchronous processor structure.

    This function does not return a value.

    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.

    Asynchronous Processor, cl_async_proc_init, cl_async_proc_destroy

Component Library: Asynchronous Processor/cl_async_proc_destroy

    cl_async_proc_destroy

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

void
cl_async_proc_destroy(
    IN  cl_async_proc_t* const  p_async_proc );

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

    This function does not return a value.

    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.

    Asynchronous Processor, cl_async_proc_construct, cl_async_proc_init

Component Library: Asynchronous Processor/cl_async_proc_init

    cl_async_proc_init

    The cl_async_proc_init function initialized an asynchronous processor
    for use.

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

    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.

    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.

    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.

    Asynchronous Processor, cl_async_proc_construct, cl_async_proc_destroy,
    cl_async_proc_queue

Component Library: Asynchronous Processor/cl_async_proc_item_t

    cl_async_proc_item_t

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

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;

    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.

    Asynchronous Processor, cl_async_proc_queue, cl_pfn_async_proc_cb_t

Component Library: Asynchronous Processor/cl_async_proc_queue

    cl_async_proc_queue

    The cl_async_proc_queue function queues a callback to an asynchronous 
    processor.

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

    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.

    This function does not return a value.

    Asynchronous Processor, cl_async_proc_init, cl_pfn_async_proc_cb_t

Component Library: Asynchronous Processor/cl_async_proc_t

    cl_async_proc_t

    Asynchronous processor structure.

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

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

} cl_async_proc_t;

    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.

    Asynchronous Processor

Component Library: Asynchronous Processor/cl_pfn_async_proc_cb_t

    cl_pfn_async_proc_cb_t

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

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

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

    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.

    Asynchronous Processor, cl_async_proc_item_t