TABLE OF CONTENTS

1. Component Library/Thread Pool
2. Component Library: Thread Pool/cl_thread_pool_construct
3. Component Library: Thread Pool/cl_thread_pool_destroy
4. Component Library: Thread Pool/cl_thread_pool_init
5. Component Library: Thread Pool/cl_thread_pool_signal
6. Component Library: Thread Pool/cl_thread_pool_t

Component Library/Thread Pool

    Thread Pool

    The Thread Pool manages a user specified number of threads.

    Each thread in the thread pool waits for a user initiated signal before
    invoking a user specified callback function. All threads in the thread
    pool invoke the same callback function.

    The thread pool functions operate on a cl_thread_pool_t structure which 
    should be treated as opaque, and should be manipulated only through the 
    provided functions.

    Structures:
        cl_thread_pool_t

    Initialization:
        cl_thread_pool_construct, cl_thread_pool_init, cl_thread_pool_destroy

    Manipulation
        cl_thread_pool_signal

Component Library: Thread Pool/cl_thread_pool_construct

    cl_thread_pool_construct

    The cl_thread_pool_construct function initializes the state of a
    thread pool.

void
cl_thread_pool_construct(
    IN  cl_thread_pool_t* const p_thread_pool );

    p_thread_pool
        [in] Pointer to a thread pool structure.

    This function does not return a value.

    Allows calling cl_thread_pool_destroy without first calling
    cl_thread_pool_init.

    Calling cl_thread_pool_construct is a prerequisite to calling any other
    thread pool function except cl_thread_pool_init.

    Thread Pool, cl_thread_pool_init, cl_thread_pool_destroy

Component Library: Thread Pool/cl_thread_pool_destroy

    cl_thread_pool_destroy

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

void
cl_thread_pool_destroy(
    IN  cl_thread_pool_t* const p_thread_pool );

    p_thread_pool
        [in] Pointer to a thread pool 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 thread pool's threads. Because of its blocking
    nature, callers of cl_thread_pool_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_thread_pool_construct or cl_thread_pool_init.

    Thread Pool, cl_thread_pool_construct, cl_thread_pool_init

Component Library: Thread Pool/cl_thread_pool_init

    cl_thread_pool_init

    The cl_thread_pool_init function creates the threads to be
    managed by a thread pool.

cl_status_t
cl_thread_pool_init(
    IN  cl_thread_pool_t* const     p_thread_pool,
    IN  uint32_t                    thread_count,
    IN  cl_pfn_thread_callback_t    pfn_callback,
    IN  const void* const           context,
    IN  const char* const           name );

    p_thread_pool
        [in] Pointer to a thread pool structure to initialize.

    thread_count
        [in] Number of threads to be managed by the thread pool.

    pfn_callback
        [in] Address of a function to be invoked by a thread.
        See the cl_pfn_thread_callback_t function type definition for
        details about the callback function.

    context
        [in] Value to pass to the callback function.

    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 pool have the same name.

    CL_SUCCESS if the thread pool creation succeeded.

    CL_INSUFFICIENT_MEMORY if there was not enough memory to inititalize
    the thread pool.

    CL_ERROR if the threads could not be created.

    cl_thread_pool_init creates and starts the specified number of threads.
    If thread_count is zero, the thread pool creates as many threads as there
    are processors in the system.

    Thread Pool, cl_thread_pool_construct, cl_thread_pool_destroy,
    cl_thread_pool_signal, cl_pfn_thread_callback_t

Component Library: Thread Pool/cl_thread_pool_signal

    cl_thread_pool_signal

    The cl_thread_pool_signal function signals a single thread of
    the thread pool to invoke the thread pool’s callback function.

cl_status_t
cl_thread_pool_signal(
    IN  cl_thread_pool_t* const p_thread_pool );

    p_thread_pool
        [in] Pointer to a thread pool structure to signal.

    CL_SUCCESS if the thread pool was successfully signalled.

    CL_ERROR otherwise.

    Each call to this function wakes up at most one waiting thread in
    the thread pool.

    If all threads are running, cl_thread_pool_signal has no effect.

    Thread Pool

Component Library: Thread Pool/cl_thread_pool_t

    cl_thread_pool_t

    Thread pool structure.

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

typedef struct _cl_thread_pool
{
    cl_pfn_thread_callback_t    pfn_callback;
    const void                  *context;
    cl_list_t                   thread_list;
    cl_event_t                  wakeup_event;
    cl_event_t                  destroy_event;
    boolean_t                   exit;
    cl_state_t                  state;
    atomic32_t                  running_count;

} cl_thread_pool_t;

    pfn_callback
        Callback function for the thread to invoke.

    context
        Context to pass to the thread callback function.

    thread_list
        List of threads managed by the thread pool.

    event
        Event used to signal threads to wake up and do work.

    destroy_event
        Event used to signal threads to exit.

    exit
        Flag used to indicates threads to exit.

    state
        State of the thread pool.

    running_count
        Number of threads running.

    Thread Pool