TABLE OF CONTENTS

1. Component Library/Quick Composite Pool
2. Component Library: Quick Composite Pool/cl_is_qcpool_inited
3. Component Library: Quick Composite Pool/cl_pfn_qcpool_dtor_t
4. Component Library: Quick Composite Pool/cl_pfn_qcpool_init_t
5. Component Library: Quick Composite Pool/cl_pool_item_t
6. Component Library: Quick Composite Pool/cl_qcpool_construct
7. Component Library: Quick Composite Pool/cl_qcpool_count
8. Component Library: Quick Composite Pool/cl_qcpool_destroy
9. Component Library: Quick Composite Pool/cl_qcpool_get
10. Component Library: Quick Composite Pool/cl_qcpool_grow
11. Component Library: Quick Composite Pool/cl_qcpool_init
12. Component Library: Quick Composite Pool/cl_qcpool_put
13. Component Library: Quick Composite Pool/cl_qcpool_put_list
14. Component Library: Quick Composite Pool/cl_qcpool_t

Component Library/Quick Composite Pool

    Quick Composite Pool

    The Quick Composite Pool provides a self-contained and self-sustaining
    pool of user defined composite objects.

    A composite object is an object that is composed of one or more
    sub-objects, each of which needs to be treated separately for
    initialization. Objects can be retrieved from the pool as long as there
    is memory in the system.

    To aid in object oriented design, the Quick Composite Pool provides users
    the ability to specify callbacks that are invoked for each object for
    construction, initialization, and destruction. Constructor and destructor
    callback functions may not fail.

    A Quick Composite Pool does not return memory to the system as the user
    returns objects to the pool. The only method of returning memory to the
    system is to destroy the pool.

    The Quick Composite Pool operates on cl_pool_item_t structures that
    describe composite objects. This provides for more efficient memory use.
    If using a cl_pool_item_t is not desired, the Composite Pool provides
    similar functionality but operates on opaque objects.

    The Quick Composit Pool functions operate on a cl_qcpool_t structure 
    which should be treated as opaque and should be manipulated only through 
    the provided functions.

    Structures:
        cl_qcpool_t, cl_pool_item_t 

    Callbacks:
        cl_pfn_qcpool_init_t, cl_pfn_qcpool_dtor_t
    
    Initialization/Destruction:
        cl_qcpool_construct, cl_qcpool_init, cl_qcpool_destroy

    Manipulation:
        cl_qcpool_get, cl_qcpool_put, cl_qcpool_put_list, cl_qcpool_grow 

    Attributes:
        cl_is_qcpool_inited, cl_qcpool_count 

Component Library: Quick Composite Pool/cl_is_qcpool_inited

    cl_is_qcpool_inited

    The cl_is_qcpool_inited function returns whether a quick composite pool was
    successfully initialized.

 uint32_t
cl_is_qcpool_inited(
    IN  const cl_qcpool_t* const    p_pool ;

    p_pool
        [in] Pointer to a cl_qcpool_t structure to check.

    TRUE if the quick composite pool was initialized successfully.

    FALSE otherwise.

    Allows checking the state of a quick composite pool to determine if
    invoking member functions is appropriate.

    Quick Composite Pool

Component Library: Quick Composite Pool/cl_pfn_qcpool_dtor_t

    cl_pfn_qcpool_dtor_t

    The cl_pfn_qcpool_dtor_t function type defines the prototype for
    functions used as destructor for objects being deallocated by a
    quick composite pool.

typedef void
(*cl_pfn_qcpool_dtor_t)(
    IN  const cl_pool_item_t* const p_pool_item,
    IN  void*                       context );

    p_pool_item
        [in] Pointer to a cl_pool_item_t structure representing an object.

    context
        [in] Context provided in a call to cl_qcpool_init.

    This function does not return a value.

    This function type is provided as function prototype reference for
    the function provided by the user as an optional parameter to the
    cl_qcpool_init function.

    The destructor is invoked once per allocated object, allowing the user
    to perform any necessary cleanup. Users should not attempt to deallocate
    the memory for the composite object, as the quick composite pool manages
    object allocation and deallocation.

    Quick Composite Pool, cl_qcpool_init

Component Library: Quick Composite Pool/cl_pfn_qcpool_init_t

    cl_pfn_qcpool_init_t

    The cl_pfn_qcpool_init_t function type defines the prototype for
    functions used as initializer for objects being allocated by a
    quick composite pool.

typedef cl_status_t
(*cl_pfn_qcpool_init_t)(
    IN  void** const            p_comp_array,
    IN  const uint32_t          num_components,
    IN  void*                   context,
    OUT cl_pool_item_t** const  pp_pool_item );

    p_comp_array
        [in] Pointer to the first entry in an array of pointers, each of
        which points to a component that makes up a composite object.

    num_components
        [in] Number of components that in the component array.

    context
        [in] Context provided in a call to cl_qcpool_init.

    pp_pool_item
        [out] Users should set this pointer to reference the cl_pool_item_t
        structure that represents the composite object.  This pointer must
        not be NULL if the function returns CL_SUCCESS.

    Return CL_SUCCESS to indicate that initialization of the object
    was successful and that initialization of further objects may continue.

    Other cl_status_t values will be returned by cl_qcpool_init
    and cl_qcpool_grow.

    This function type is provided as function prototype reference for
    the function provided by the user as a parameter to the
    cl_qcpool_init function.

    The initializer is invoked once per allocated object, allowing the user
    to chain components to form a composite object and perform any necessary
    initialization.  Returning a status other than CL_SUCCESS aborts a grow
    operation, initiated either through cl_qcpool_init or cl_qcpool_grow,
    and causes the initiating function to fail.  Any non-CL_SUCCESS status
    will be returned by the function that initiated the grow operation.

    All memory for the requested number of components is pre-allocated.  Users
    should include space in one of their components for the cl_pool_item_t
    structure that will represent the composite object to avoid having to
    allocate that structure in the initialization callback.  Alternatively,
    users may specify an additional component for the cl_pool_item_t structure.

    When later performing a cl_qcpool_get call, the return value is a pointer
    to the cl_pool_item_t returned by this function in the pp_pool_item
    parameter. Users must set pp_pool_item to a valid pointer to the
    cl_pool_item_t representing the object if they return CL_SUCCESS.

    Quick Composite Pool, cl_qcpool_init

Component Library: Quick Composite Pool/cl_pool_item_t

    cl_pool_item_t

    The cl_pool_item_t structure is used by pools to store objects.

typedef struct _cl_pool_item
{
    cl_list_item_t      list_item;
#ifdef _DEBUG_
    /* Pointer to the owner pool used for sanity checks. */
    struct _cl_qcpool   *p_pool;
#endif

} cl_pool_item_t;

    list_item
        Used internally by the pool. Users should not use this field.

    p_pool
        Used internally by the pool in debug builds to check for consistency.

    The pool item structure is defined in such a way as to safely allow
    users to cast from a pool item to a list item for storing items
    retrieved from a quick pool in a quick list.

    Quick Composite Pool, cl_list_item_t

Component Library: Quick Composite Pool/cl_qcpool_construct

    cl_qcpool_construct

    The cl_qcpool_construct function constructs a quick composite pool.

void
cl_qcpool_construct(
    IN  cl_qcpool_t* const  p_pool );

    p_pool
        [in] Pointer to a cl_qcpool_t structure whose state to initialize.

    This function does not return a value.

    Allows calling cl_qcpool_init, cl_qcpool_destroy, cl_is_qcpool_inited.

    Calling cl_qcpool_construct is a prerequisite to calling any other
    quick composite pool function except cl_qcpool_init.

    Quick Composite Pool, cl_qcpool_init, cl_qcpool_destroy,
    cl_is_qcpool_inited

Component Library: Quick Composite Pool/cl_qcpool_count

    cl_qcpool_count

    The cl_qcpool_count function returns the number of available objects
    in a quick composite pool.

 size_t
cl_qcpool_count(
    IN  cl_qcpool_t* const  p_pool ;

    p_pool
        [in] Pointer to a cl_qcpool_t structure for which the number of
        available objects is requested.

    Returns the number of objects available in the specified
    quick composite pool.

    Quick Composite Pool

Component Library: Quick Composite Pool/cl_qcpool_destroy

    cl_qcpool_destroy

    The cl_qcpool_destroy function destroys a quick composite pool.

void
cl_qcpool_destroy(
    IN  cl_qcpool_t* const  p_pool );

    p_pool
        [in] Pointer to a cl_qcpool_t structure to destroy.

    This function does not return a value.

    All memory allocated for composite objects is freed. The destructor
    callback, if any, will be invoked for every allocated object. Further
    operations on the composite pool should not be attempted after
    cl_qcpool_destroy is invoked.

    This function should only be called after a call to
    cl_qcpool_construct or cl_qcpool_init.

    In a debug build, cl_qcpool_destroy asserts that all objects are in
    the pool.

    Quick Composite Pool, cl_qcpool_construct, cl_qcpool_init

Component Library: Quick Composite Pool/cl_qcpool_get

    cl_qcpool_get

    The cl_qcpool_get function retrieves an object from a
    quick composite pool.

cl_pool_item_t*
cl_qcpool_get(
    IN  cl_qcpool_t* const  p_pool );

    p_pool
        [in] Pointer to a cl_qcpool_t structure from which to retrieve
        an object.

    Returns a pointer to a cl_pool_item_t for a composite object.

    Returns NULL if the pool is empty and can not be grown automatically.

    cl_qcpool_get returns the object at the head of the pool. If the pool is
    empty, it is automatically grown to accommodate this request unless the
    grow_size parameter passed to the cl_qcpool_init function was zero.

    Quick Composite Pool, cl_qcpool_get_tail, cl_qcpool_put,
    cl_qcpool_grow, cl_qcpool_count

Component Library: Quick Composite Pool/cl_qcpool_grow

    cl_qcpool_grow

    The cl_qcpool_grow function grows a quick composite pool by
    the specified number of objects.

cl_status_t
cl_qcpool_grow(
    IN  cl_qcpool_t* const      p_pool,
    IN  uint32_t                obj_count );

    p_pool
        [in] Pointer to a cl_qcpool_t structure whose capacity to grow.

    obj_count
        [in] Number of objects by which to grow the pool.

    CL_SUCCESS if the quick composite pool grew successfully.

    CL_INSUFFICIENT_MEMORY if there was not enough memory to grow the
    quick composite pool.

    cl_status_t value returned by optional initialization callback function
    specified by the pfn_initializer parameter passed to the
    cl_qcpool_init function.

    It is not necessary to call cl_qcpool_grow if the pool is
    configured to grow automatically.

    Quick Composite Pool

Component Library: Quick Composite Pool/cl_qcpool_init

    cl_qcpool_init

    The cl_qcpool_init function initializes a quick composite pool for use.

cl_status_t
cl_qcpool_init(
    IN  cl_qcpool_t* const      p_pool,
    IN  const size_t            min_size,
    IN  const size_t            max_size,
    IN  const size_t            grow_size,
    IN  const size_t* const     component_sizes,
    IN  const uint32_t          num_components,
    IN  cl_pfn_qcpool_init_t    pfn_initializer OPTIONAL,
    IN  cl_pfn_qcpool_dtor_t    pfn_destructor OPTIONAL,
    IN  const void* const       context );

    p_pool
        [in] Pointer to a cl_qcpool_t structure to initialize.

    min_size
        [in] Minimum number of objects that the pool should support. All
        necessary allocations to allow storing the minimum number of items
        are performed at initialization time, and all necessary callbacks
        successfully invoked.

    max_size
        [in] Maximum number of objects to which the pool is allowed to grow.
        A value of zero specifies no maximum.

    grow_size
        [in] Number of objects to allocate when incrementally growing the pool.
        A value of zero disables automatic growth.

    component_sizes
        [in] Pointer to the first entry in an array of sizes describing,
        in order, the sizes of the components that make up a composite object.

    num_components
        [in] Number of components that make up a composite object.

    pfn_initializer
        [in] Initializer callback to invoke for every new object when growing
        the pool. This parameter may be NULL only if the objects stored in
        the quick composite pool consist of only one component. If NULL, the
        pool assumes the cl_pool_item_t structure describing objects is
        located at the head of each object. See the cl_pfn_qcpool_init_t
        function type declaration for details about the callback function.

    pfn_destructor
        [in] Destructor callback to invoke for every object before memory for
        that object is freed. This parameter is optional and may be NULL.
        See the cl_pfn_qcpool_dtor_t function type declaration for details
        about the callback function.

    context
        [in] Value to pass to the callback functions to provide context.

    CL_SUCCESS if the quick composite pool was initialized successfully.

    CL_INSUFFICIENT_MEMORY if there was not enough memory to initialize the
    quick composite pool.

    CL_INVALID_SETTING if a NULL constructor was provided for composite objects
    consisting of more than one component.  Also returns CL_INVALID_SETTING if
    the maximum size is non-zero and less than the minimum size.

    Other cl_status_t value returned by optional initialization callback function
    specified by the pfn_initializer parameter.

    If initialization fails, the pool is left in a destroyed state.  Callers
    may still safely call cl_qcpool_destroy.

    cl_qcpool_init initializes, and if necessary, grows the pool to
    the capacity desired.

    Quick Composite Pool, cl_qcpool_construct, cl_qcpool_destroy,
    cl_qcpool_get, cl_qcpool_put, cl_qcpool_grow,
    cl_qcpool_count, cl_pfn_qcpool_init_t, cl_pfn_qcpool_dtor_t

Component Library: Quick Composite Pool/cl_qcpool_put

    cl_qcpool_put

    The cl_qcpool_put function returns an object to a quick composite pool.

 void
cl_qcpool_put(
    IN  cl_qcpool_t* const      p_pool,
    IN  cl_pool_item_t* const   p_pool_item ;

    p_pool
        [in] Pointer to a cl_qcpool_t structure to which to return
        an object.

    p_pool_item
        [in] Pointer to a cl_pool_item_t structure for the object
        being returned.

    This function does not return a value.

    cl_qcpool_put places the returned object at the head of the pool.

    The object specified by the p_pool_item parameter must have been
    retrieved from the pool by a previous call to cl_qcpool_get.

    Quick Composite Pool, cl_qcpool_put_tail, cl_qcpool_get

Component Library: Quick Composite Pool/cl_qcpool_put_list

    cl_qcpool_put_list

    The cl_qcpool_put_list function returns a list of objects to the head of
    a quick composite pool.

 void
cl_qcpool_put_list(
    IN  cl_qcpool_t* const  p_pool,
    IN  cl_qlist_t* const   p_list ;

    p_pool
        [in] Pointer to a cl_qcpool_t structure to which to return
        a list of objects.

    p_list
        [in] Pointer to a cl_qlist_t structure for the list of objects
        being returned.

    This function does not return a value.

    cl_qcpool_put_list places the returned objects at the head of the pool.

    The objects in the list specified by the p_list parameter must have been
    retrieved from the pool by a previous call to cl_qcpool_get.

    Quick Composite Pool, cl_qcpool_put, cl_qcpool_put_tail, cl_qcpool_get

Component Library: Quick Composite Pool/cl_qcpool_t

    cl_qcpool_t

    Quick composite pool structure.

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

typedef struct _cl_qcpool
{
    uint32_t                num_components;
    size_t                  *component_sizes;
    void                    **p_components;
    size_t                  num_objects;
    size_t                  max_objects;
    size_t                  grow_size;
    cl_pfn_qcpool_init_t    pfn_init;
    cl_pfn_qcpool_dtor_t    pfn_dtor;
    const void              *context;
    cl_qlist_t              free_list;
    cl_qlist_t              alloc_list;
    cl_state_t              state;

} cl_qcpool_t;

    num_components
        Number of components per object.

    component_sizes
        Array of sizes, one for each component.

    p_components
        Array of pointers to components, used for the constructor callback.

    num_objects
        Number of objects managed by the pool

    grow_size
        Number of objects to add when automatically growing the pool.

    pfn_init
        Pointer to the user's initializer callback to invoke when initializing
        new objects.

    pfn_dtor
        Pointer to the user's destructor callback to invoke before deallocating
        memory allocated for objects.

    context
        User's provided context for callback functions, used by the pool
        when invoking callbacks.

    free_list
        Quick list of objects available.

    alloc_list
        Quick list used to store information about allocations.

    state
        State of the pool.

    Quick Composite Pool