TABLE OF CONTENTS

1. Component Library/List
2. Component Library: List/cl_is_list_empty
3. Component Library: List/cl_is_list_inited
4. Component Library: List/cl_is_object_in_list
5. Component Library: List/cl_list_apply_func
6. Component Library: List/cl_list_construct
7. Component Library: List/cl_list_count
8. Component Library: List/cl_list_destroy
9. Component Library: List/cl_list_end
10. Component Library: List/cl_list_find_from_head
11. Component Library: List/cl_list_find_from_tail
12. Component Library: List/cl_list_head
13. Component Library: List/cl_list_init
14. Component Library: List/cl_list_insert_array_head
15. Component Library: List/cl_list_insert_array_tail
16. Component Library: List/cl_list_insert_head
17. Component Library: List/cl_list_insert_next
18. Component Library: List/cl_list_insert_prev
19. Component Library: List/cl_list_insert_tail
20. Component Library: List/cl_list_iterator_t
21. Component Library: List/cl_list_next
22. Component Library: List/cl_list_obj
23. Component Library: List/cl_list_prev
24. Component Library: List/cl_list_remove_all
25. Component Library: List/cl_list_remove_head
26. Component Library: List/cl_list_remove_item
27. Component Library: List/cl_list_remove_object
28. Component Library: List/cl_list_remove_tail
29. Component Library: List/cl_list_t
30. Component Library: List/cl_list_tail
31. Component Library: List/cl_pfn_list_apply_t
32. Component Library: List/cl_pfn_list_find_t

Component Library/List

    List

    List stores objects in a doubly linked list.

    Unlike quick list, users pass pointers to the object being stored, rather
    than to a cl_list_item_t structure.  Insertion operations on a list can
    fail, and callers should trap for such failures.

    Use quick list in situations where insertion failures cannot be tolerated.

    List is not thread safe, and users must provide serialization.

    The list functions operates on a cl_list_t structure which should be 
    treated as opaque and should be manipulated only through the provided 
    functions.

    Types:
        cl_list_iterator_t

    Structures:
        cl_list_t

    Callbacks:
        cl_pfn_list_apply_t, cl_pfn_list_find_t

    Initialization/Destruction:
        cl_list_construct, cl_list_init, cl_list_destroy

    Iteration:
        cl_list_next, cl_list_prev, cl_list_head, cl_list_tail, 
        cl_list_end

    Manipulation:
        cl_list_insert_head, cl_list_insert_tail, 
        cl_list_insert_array_head, cl_list_insert_array_tail, 
        cl_list_insert_prev, cl_list_insert_next, 
        cl_list_remove_head, cl_list_remove_tail, 
        cl_list_remove_object, cl_list_remove_item, cl_list_remove_all

    Search:
        cl_is_object_in_list, cl_list_find_from_head, cl_list_find_from_tail,
        cl_list_apply_func

    Attributes:
        cl_list_count, cl_is_list_empty, cl_is_list_inited

Component Library: List/cl_is_list_empty

    cl_is_list_empty

    The cl_is_list_empty function returns whether a list is empty.

 boolean_t
cl_is_list_empty(
    IN  const cl_list_t* const  p_list ;

    p_list
        [in] Pointer to a cl_list_t structure.

    TRUE if the specified list is empty.

    FALSE otherwise.

    List, cl_list_count, cl_list_remove_all

Component Library: List/cl_is_list_inited

    cl_is_list_inited

    The cl_is_list_inited function returns whether a list was
    initialized successfully.

 boolean_t
cl_is_list_inited(
    IN  const cl_list_t* const  p_list ;

    p_list
        [in] Pointer to a cl_list_t structure whose initilization state
        to check.

    TRUE if the list was initialized successfully.

    FALSE otherwise.

    Allows checking the state of a list to determine if invoking
    member functions is appropriate.

    List

Component Library: List/cl_is_object_in_list

    cl_is_object_in_list

    The cl_is_object_in_list function returns whether an object
    is stored in a list.

boolean_t
cl_is_object_in_list(
    IN  const cl_list_t* const  p_list,
    IN  const void* const       p_object );

    p_list
        [in] Pointer to a cl_list_t structure in which to look for the object.

    p_object
        [in] Pointer to an object stored in a list.

    TRUE if p_object was found in the list.

    FALSE otherwise.

    List

Component Library: List/cl_list_apply_func

    cl_list_apply_func

    The cl_list_apply_func function executes a specified function for every
    object stored in a list.

void
cl_list_apply_func(
    IN  const cl_list_t* const  p_list,
    IN  cl_pfn_list_apply_t     pfn_func,
    IN  const void* const       context );

    p_list
        [in] Pointer to a cl_list_t structure to iterate.

    pfn_func
        [in] Function invoked for every item in a list.
        See the cl_pfn_list_apply_t function type declaration for details
        about the callback function.

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

    This function does not return a value.

    cl_list_apply_func invokes the specified callback function for every
    object stored in the list, starting from the head.  The function specified
    by the pfn_func parameter must not perform any list operations as these
    would corrupt the list.

    List, cl_list_find_from_head, cl_list_find_from_tail,
    cl_pfn_list_apply_t

Component Library: List/cl_list_construct

    cl_list_construct

    The cl_list_construct function constructs a list.

void
cl_list_construct(
    IN  cl_list_t* const    p_list );

    p_list
        [in] Pointer to cl_list_t object whose state to initialize.

    This function does not return a value.

    Allows calling cl_list_init, cl_list_destroy and cl_is_list_inited.

    Calling cl_list_construct is a prerequisite to calling any other
    list function except cl_list_init.

    List, cl_list_init, cl_list_destroy, cl_is_list_inited

Component Library: List/cl_list_count

    cl_list_count

    The cl_list_count function returns the number of objects stored in a list.

 size_t
cl_list_count(
    IN  const cl_list_t* const  p_list ;

    p_list
        [in] Pointer to a cl_list_t structure whose object to count.

    Number of objects stored in the specified list.

    List

Component Library: List/cl_list_destroy

    cl_list_destroy

    The cl_list_destroy function destroys a list.

void
cl_list_destroy(
    IN  cl_list_t* const    p_list );

    p_list
        [in] Pointer to cl_list_t structure to destroy.

    This function does not return a value.

    cl_list_destroy does not affect any of the objects stored in the list,
    but does release all memory allocated internally.  Further operations
    should not be attempted on the list after cl_list_destroy is invoked.

    This function should only be called after a call to cl_list_construct
    or cl_list_init.

    In debug builds, cl_list_destroy asserts if the list is not empty.

    List, cl_list_construct, cl_list_init

Component Library: List/cl_list_end

    cl_list_end

    The cl_list_end function returns returns the list iterator for
    the end of a list.

 const cl_list_iterator_t
cl_list_end(
    IN  const cl_list_t* const  p_list ;

    p_list
        [in] Pointer to a cl_list_t structure for which the iterator for the
        object at the head is to be returned.

    cl_list_iterator_t for the end of the list.

    Use cl_list_obj to retrieve the object associated with the
    returned cl_list_iterator_t.

    List, cl_list_head, cl_list_tail, cl_list_next, cl_list_prev,
    cl_list_obj

Component Library: List/cl_list_find_from_head

    cl_list_find_from_head

    The cl_list_find_from_head function uses a specified function
    to search for an object starting from the head of a list.

const cl_list_iterator_t
cl_list_find_from_head(
    IN  const cl_list_t* const  p_list,
    IN  cl_pfn_list_find_t      pfn_func,
    IN  const void* const       context );

    p_list
        [in] Pointer to a cl_list_t structure to search.

    pfn_func
        [in] Function invoked to determine if a match was found.
        See the cl_pfn_list_find_t function type declaration for details
        about the callback function.

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

    Returns the iterator for the object if found.

    Returns the iterator for the list end otherwise.

    cl_list_find_from_head does not remove the found object from
    the list.  The iterator for the object is returned when the function
    provided by the pfn_func parameter returns CL_SUCCESS.  The function
    specified by the pfn_func parameter must not perform any list
    operations as these would corrupt the list.

    List, cl_list_find_from_tail, cl_list_apply_func_t,
    cl_pfn_list_find_t

Component Library: List/cl_list_find_from_tail

    cl_list_find_from_tail

    The cl_list_find_from_tail function uses a specified function
    to search for an object starting from the tail of a list.

const cl_list_iterator_t
cl_list_find_from_tail(
    IN  const cl_list_t* const  p_list,
    IN  cl_pfn_list_find_t      pfn_func,
    IN  const void* const       context );

    p_list
        [in] Pointer to a cl_list_t structure to search.

    pfn_func
        [in] Function invoked to determine if a match was found.
        See the cl_pfn_list_find_t function type declaration for details
        about the callback function.

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

    Returns the iterator for the object if found.

    Returns the iterator for the list end otherwise.

    cl_list_find_from_tail does not remove the found object from
    the list.  The iterator for the object is returned when the function
    provided by the pfn_func parameter returns CL_SUCCESS.  The function
    specified by the pfn_func parameter must not perform any list
    operations as these would corrupt the list.

    List, cl_list_find_from_head, cl_list_apply_func_t,
    cl_pfn_list_find_t

Component Library: List/cl_list_head

    cl_list_head

    The cl_list_head function returns returns a list iterator for
    the head of a list.

 const cl_list_iterator_t
cl_list_head(
    IN  const cl_list_t* const  p_list ;

    p_list
        [in] Pointer to a cl_list_t structure for which the iterator for the
        object at the head is to be returned.

    cl_list_iterator_t for the head of the list.

    cl_list_iterator_t for the end of the list if the list is empty.

    Use cl_list_obj to retrieve the object associated with the
    returned cl_list_iterator_t.

    List, cl_list_tail, cl_list_next, cl_list_prev, cl_list_end,
    cl_list_obj

Component Library: List/cl_list_init

    cl_list_init

    The cl_list_init function initializes a list for use.

cl_status_t
cl_list_init(
    IN  cl_list_t* const    p_list,
    IN  const size_t        min_items );

    p_list
        [in] Pointer to cl_list_t structure to initialize.

    min_items
        [in] Minimum number of items that can be stored.  All necessary
        allocations to allow storing the minimum number of items is performed
        at initialization time.

    CL_SUCCESS if the list was initialized successfully.

    CL_INSUFFICIENT_MEMORY if there was not enough memory for initialization.

    The list will always be able to store at least as many items as specified
    by the min_items parameter.

    List, cl_list_construct, cl_list_destroy, cl_list_insert_head,
    cl_list_insert_tail, cl_list_remove_head, cl_list_remove_tail

Component Library: List/cl_list_insert_array_head

    cl_list_insert_array_head

 DESCRIPTION:
    The cl_list_insert_array_head function inserts an array of objects
    at the head of a list.

cl_status_t
cl_list_insert_array_head(
    IN  cl_list_t* const    p_list,
    IN  const void* const   p_array,
    IN  uint32_t            item_count,
    IN  const uint32_t      item_size );

    p_list
        [in] Pointer to a cl_list_t structure into which to insert the objects.

    p_array
        [in] Pointer to the first object in an array.

    item_count
        [in] Number of objects in the array.

    item_size
        [in] Size of the objects added to the list.  This is the stride in the
        array from one object to the next.

    CL_SUCCESS if the insertion was successful.

    CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.

    Inserts all objects in the array to the head of the list, preserving the
    ordering of the objects.  If not successful, no items are added.
    List insertion operations are guaranteed to work for the minimum number
    of items as specified in cl_list_init by the min_items parameter.

    List, cl_list_insert_array_tail, cl_list_insert_head, cl_list_insert_tail,
    cl_list_insert_prev, cl_list_insert_next

Component Library: List/cl_list_insert_array_tail

    cl_list_insert_array_tail

    The cl_list_insert_array_tail function inserts an array of objects
    at the tail of a list.

cl_status_t
cl_list_insert_array_tail(
    IN  cl_list_t* const    p_list,
    IN  const void* const   p_array,
    IN  uint32_t            item_count,
    IN  const uint32_t      item_size);

    p_list
        [in] Pointer to a cl_list_t structure into which to insert the objects.

    p_array
        [in] Pointer to the first object in an array.

    item_count
        [in] Number of objects in the array.

    item_size
        [in] Size of the objects added to the list.  This is the stride in the
        array from one object to the next.

    CL_SUCCESS if the insertion was successful.

    CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.

    Inserts all objects in the array to the tail of the list, preserving the
    ordering of the objects.  If not successful, no items are added.
    List insertion operations are guaranteed to work for the minimum number
    of items as specified in cl_list_init by the min_items parameter.

    List, cl_list_insert_array_head, cl_list_insert_head, cl_list_insert_tail,
    cl_list_insert_prev, cl_list_insert_next

Component Library: List/cl_list_insert_head

    cl_list_insert_head

    The cl_list_insert_head function inserts an object at the head of a list.

 cl_status_t
cl_list_insert_head(
    IN  cl_list_t* const    p_list,
    IN  const void* const   p_object ;

    p_list
        [in] Pointer to a cl_list_t structure into which to insert the object.

    p_object
        [in] Pointer to an object to insert into the list.

    CL_SUCCESS if the insertion was successful.

    CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.

    Inserts the specified object at the head of the list.  List insertion
    operations are guaranteed to work for the minimum number of items as
    specified in cl_list_init by the min_items parameter.

    List, cl_list_insert_tail, cl_list_insert_array_head,
    cl_list_insert_array_tail, cl_list_insert_prev, cl_list_insert_next,
    cl_list_remove_head

Component Library: List/cl_list_insert_next

    cl_list_insert_next

    The cl_list_insert_next function inserts an object in a list after
    the object associated with a given iterator.

 cl_status_t
cl_list_insert_next(
    IN  cl_list_t* const            p_list,
    IN  const cl_list_iterator_t    iterator,
    IN  const void* const           p_object ;

    p_list
        [in] Pointer to a cl_list_t structure into which to insert the object.

    iterator
        [in] cl_list_iterator_t returned by a previous call to cl_list_head,
        cl_list_tail, cl_list_next, or cl_list_prev.

    p_object
        [in] Pointer to an object to insert into the list.

    CL_SUCCESS if the insertion was successful.

    CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.

    List, cl_list_insert_prev, cl_list_insert_head, cl_list_insert_tail,
    cl_list_insert_array_head, cl_list_insert_array_tail

Component Library: List/cl_list_insert_prev

    cl_list_insert_prev

    The cl_list_insert_prev function inserts an object in a list before
    the object associated with a given iterator.

 cl_status_t
cl_list_insert_prev(
    IN  cl_list_t* const            p_list,
    IN  const cl_list_iterator_t    iterator,
    IN  const void* const           p_object ;

    p_list
        [in] Pointer to a cl_list_t structure into which to insert the object.

    iterator
        [in] cl_list_iterator_t returned by a previous call to cl_list_head,
        cl_list_tail, cl_list_next, or cl_list_prev.

    p_object
        [in] Pointer to an object to insert into the list.

    CL_SUCCESS if the insertion was successful.

    CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.

    List, cl_list_insert_next, cl_list_insert_head, cl_list_insert_tail,
    cl_list_insert_array_head, cl_list_insert_array_tail

Component Library: List/cl_list_insert_tail

    cl_list_insert_tail

    The cl_list_insert_tail function inserts an object at the head of a list.

 cl_status_t
cl_list_insert_tail(
    IN  cl_list_t* const    p_list,
    IN  const void* const   p_object ;

    p_list
        [in] Pointer to a cl_list_t structure into which to insert the object.

    p_object
        [in] Pointer to an object to insert into the list.

    CL_SUCCESS if the insertion was successful.

    CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.

    Inserts the specified object at the tail of the list.  List insertion
    operations are guaranteed to work for the minimum number of items as
    specified in cl_list_init by the min_items parameter.

    List, cl_list_insert_head, cl_list_insert_array_head,
    cl_list_insert_array_tail, cl_list_insert_prev, cl_list_insert_next,
    cl_list_remove_tail

Component Library: List/cl_list_iterator_t

    cl_list_iterator_t

    Iterator type used to walk a list.

typedef const cl_list_item_t *cl_list_iterator_t;

    The iterator should be treated as opaque to prevent corrupting the list.

    List, cl_list_head, cl_list_tail, cl_list_next, cl_list_prev,
    cl_list_obj

Component Library: List/cl_list_next

    cl_list_next

    The cl_list_next function returns a list iterator for the object stored
    in a list after the object associated with a given list iterator.

 const cl_list_iterator_t
cl_list_next(
    IN  const cl_list_iterator_t    iterator ;

    p_list
        [in] Pointer to a cl_list_t structure for which the iterator for the
        next object is to be returned.

    iterator
        [in] cl_list_iterator_t returned by a previous call to cl_list_head,
        cl_list_tail, cl_list_next, or cl_list_prev.

    cl_list_iterator_t for the object following the object associated with
    the list iterator specified by the iterator parameter.

    cl_list_iterator_t for the end of the list if the list is empty.

    Use cl_list_obj to retrieve the object associated with the
    returned cl_list_iterator_t.

    List, cl_list_prev, cl_list_head, cl_list_tail, cl_list_end,
    cl_list_obj

Component Library: List/cl_list_obj

    cl_list_obj

    The cl_list_obj function returns the object associated
    with a list iterator.

 void*
cl_list_obj(
    IN  const cl_list_iterator_t    iterator ;

    iterator
        [in] cl_list_iterator_t returned by a previous call to cl_list_head,
        cl_list_tail, cl_list_next, or cl_list_prev whose object is requested.

    Pointer to the object associated with the list iterator specified
    by the iterator parameter.

    List, cl_list_head, cl_list_tail, cl_list_next, cl_list_prev

Component Library: List/cl_list_prev

    cl_list_prev

    The cl_list_prev function returns a list iterator for the object stored
    in a list before the object associated with a given list iterator.

 const cl_list_iterator_t
cl_list_prev(
    IN  const cl_list_iterator_t    iterator ;

    p_list
        [in] Pointer to a cl_list_t structure for which the iterator for the
        next object is to be returned.

    iterator
        [in] cl_list_iterator_t returned by a previous call to cl_list_head,
        cl_list_tail, cl_list_next, or cl_list_prev.

    cl_list_iterator_t for the object preceding the object associated with
    the list iterator specified by the iterator parameter.

    cl_list_iterator_t for the end of the list if the list is empty.

    Use cl_list_obj to retrieve the object associated with the
    returned cl_list_iterator_t.

    List, cl_list_next, cl_list_head, cl_list_tail, cl_list_end,
    cl_list_obj

Component Library: List/cl_list_remove_all

    cl_list_remove_all

    The cl_list_remove_all function removes all objects from a list,
    leaving it empty.

 void
cl_list_remove_all(
    IN  cl_list_t* const    p_list ;

    p_list
        [in] Pointer to a cl_list_t structure from which to remove all objects.

    This function does not return a value.

    List, cl_list_remove_head, cl_list_remove_tail, cl_list_remove_object,
    cl_list_remove_item

Component Library: List/cl_list_remove_head

    cl_list_remove_head

    The cl_list_remove_head function removes an object from the head of a list.

 void*
cl_list_remove_head(
    IN  cl_list_t* const    p_list ;

    p_list
        [in] Pointer to a cl_list_t structure from which to remove an object.

    Returns the pointer to the object formerly at the head of the list.

    NULL if the list was empty.

    List, cl_list_remove_tail, cl_list_remove_all, cl_list_remove_object,
    cl_list_remove_item, cl_list_insert_head

Component Library: List/cl_list_remove_item

    cl_list_remove_item

    The cl_list_remove_item function removes an object from the head of a list.

 void
cl_list_remove_item(
    IN  cl_list_t* const            p_list,
    IN  const cl_list_iterator_t    iterator ;

    p_list
        [in] Pointer to a cl_list_t structure from which to remove the item.

    iterator
        [in] cl_list_iterator_t returned by a previous call to cl_list_head,
        cl_list_tail, cl_list_next, or cl_list_prev.

    This function does not return a value.

    List, cl_list_remove_object, cl_list_remove_head, cl_list_remove_tail,
    cl_list_remove_all

Component Library: List/cl_list_remove_object

    cl_list_remove_object

    The cl_list_remove_object function removes a specific object from a list.

cl_status_t
cl_list_remove_object(
    IN  cl_list_t* const    p_list,
    IN  const void* const   p_object );

    p_list
        [in] Pointer to a cl_list_t structure from which to remove the object.

    p_object
        [in] Pointer to an object to remove from the list.

    CL_SUCCESS if the object was removed.

    CL_NOT_FOUND if the object was not found in the list.

    Removes the first occurrence of an object from a list.

    List, cl_list_remove_item, cl_list_remove_head, cl_list_remove_tail,
    cl_list_remove_all

Component Library: List/cl_list_remove_tail

    cl_list_remove_tail

    The cl_list_remove_tail function removes an object from the tail of a list.

 void*
cl_list_remove_tail(
    IN  cl_list_t* const    p_list ;

    p_list
        [in] Pointer to a cl_list_t structure from which to remove an object.

    Returns the pointer to the object formerly at the tail of the list.

    NULL if the list was empty.

    List, cl_list_remove_head, cl_list_remove_all, cl_list_remove_object,
    cl_list_remove_item, cl_list_insert_head

Component Library: List/cl_list_t

    cl_list_t

    List structure.

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

typedef struct _cl_list
{
    cl_qlist_t          list;
    cl_qpool_t          list_item_pool;

} cl_list_t;

    list
        Quick list of items stored in the list.

    list_item_pool
        Quick pool of list objects for storing objects in the quick list.

    List

Component Library: List/cl_list_tail

    cl_list_tail

    The cl_list_tail function returns returns a list iterator for
    the tail of a list.

 const cl_list_iterator_t
cl_list_tail(
    IN  const cl_list_t* const  p_list ;

    p_list
        [in] Pointer to a cl_list_t structure for which the iterator for the
        object at the tail is to be returned.

    cl_list_iterator_t for the tail of the list.

    cl_list_iterator_t for the end of the list if the list is empty.

    Use cl_list_obj to retrieve the object associated with the

    returned cl_list_iterator_t.

    List, cl_list_head, cl_list_next, cl_list_prev, cl_list_end,
    cl_list_obj

Component Library: List/cl_pfn_list_apply_t

    cl_pfn_list_apply_t

    The cl_pfn_list_apply_t function type defines the prototype for functions
    used to iterate objects in a list.

typedef void
(*cl_pfn_list_apply_t)(
    IN  void* const         p_object,
    IN  void*               context );

    p_object
        [in] Pointer to an object stored in a list.

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

    This function does not return a value.

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

    List, cl_list_apply_func

Component Library: List/cl_pfn_list_find_t

    cl_pfn_list_find_t

    The cl_pfn_list_find_t function type defines the prototype for functions
    used to find objects in a list.

typedef cl_status_t
(*cl_pfn_list_find_t)(
    IN  const void* const   p_object,
    IN  void*               context );

    p_object
        [in] Pointer to an object stored in a list.

    context
        [in] Context provided in a call to ListFindFromHead or ListFindFromTail.

    Return CL_SUCCESS if the desired item was found.  This stops list iteration.

    Return CL_NOT_FOUND to continue the list iteration.

    This function type is provided as function prototype reference for the
    function provided by users as a parameter to the cl_list_find_from_head
    and cl_list_find_from_tail functions.

    List, cl_list_find_from_head, cl_list_find_from_tail