TABLE OF CONTENTS

1. Component Library/Map
2. Component Library: Event/cl_is_map_inited
3. Component Library: Map/cl_is_map_empty
4. Component Library: Map/cl_map_construct
5. Component Library: Map/cl_map_count
6. Component Library: Map/cl_map_delta
7. Component Library: Map/cl_map_destroy
8. Component Library: Map/cl_map_end
9. Component Library: Map/cl_map_get
10. Component Library: Map/cl_map_head
11. Component Library: Map/cl_map_init
12. Component Library: Map/cl_map_insert
13. Component Library: Map/cl_map_iterator_t
14. Component Library: Map/cl_map_key
15. Component Library: Map/cl_map_merge
16. Component Library: Map/cl_map_next
17. Component Library: Map/cl_map_obj
18. Component Library: Map/cl_map_prev
19. Component Library: Map/cl_map_remove
20. Component Library: Map/cl_map_remove_all
21. Component Library: Map/cl_map_remove_item
22. Component Library: Map/cl_map_t
23. Component Library: Map/cl_map_tail

Component Library/Map

    Map

    Map implements a binary tree that stores user objects.  Each item stored
    in a map has a unique 64-bit key (duplicates are not allowed).  Map
    provides the ability to efficiently search for an item given a key.

    Map may allocate memory when inserting objects, and can therefore fail
    operations due to insufficient memory.  Use quick map in situations where
    such insertion failures cannot be tolerated.

    Map is not thread safe, and users must provide serialization when adding
    and removing items from the map.

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

    Types:
        cl_map_iterator_t

    Structures:
        cl_map_t, cl_map_item_t, cl_map_obj_t

    Item Manipulation:
        cl_map_obj, cl_map_key

    Initialization:
        cl_map_construct, cl_map_init, cl_map_destroy

    Iteration:
        cl_map_end, cl_map_head, cl_map_tail, cl_map_next, cl_map_prev

    Manipulation
        cl_map_insert, cl_map_get, cl_map_remove_item, cl_map_remove, 
        cl_map_remove_all, cl_map_merge, cl_map_delta

    Attributes:
        cl_map_count, cl_is_map_empty, cl_is_map_inited

Component Library: Event/cl_is_map_inited

    cl_is_map_inited

    The cl_is_map_inited function returns whether a map was
    successfully initialized.

 boolean_t
cl_is_map_inited(
    IN  const cl_map_t* const   p_map ;

    p_map
        [in] Pointer to a cl_map_t structure whose initialization state
        to check.

    TRUE if the map was initialized successfully.

    FALSE otherwise.

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

    Map

Component Library: Map/cl_is_map_empty

    cl_is_map_empty

    The cl_is_map_empty function returns whether a map is empty.

 boolean_t
cl_is_map_empty(
    IN  const cl_map_t* const   p_map ;

    p_map
        [in] Pointer to a map to test for emptiness.

    TRUE if the map is empty.

    FALSE otherwise.

    Map, cl_map_count, cl_map_remove_all

Component Library: Map/cl_map_construct

    cl_map_construct

    The cl_map_construct function constructs a map.

void
cl_map_construct(
    IN  cl_map_t* const p_map );

    p_map
        [in] Pointer to a cl_map_t structure to construct.

    This function does not return a value.

    Allows calling cl_map_init, cl_map_destroy, and cl_is_map_inited.

    Calling cl_map_construct is a prerequisite to calling any other
    map function except cl_map_init.

    Map, cl_map_init, cl_map_destroy, cl_is_map_inited

Component Library: Map/cl_map_count

    cl_map_count

    The cl_map_count function returns the number of items stored
    in a map.

 size_t
cl_map_count(
    IN  const cl_map_t* const   p_map ;

    p_map
        [in] Pointer to a map whose item count to return.

    Returns the number of items stored in the map.

    Map, cl_is_map_empty

Component Library: Map/cl_map_delta

    cl_map_delta

    The cl_map_delta function computes the differences between two maps.

cl_status_t
cl_map_delta(
    IN OUT  cl_map_t* const p_map1,
    IN OUT  cl_map_t* const p_map2,
    OUT     cl_map_t* const p_new,
    OUT     cl_map_t* const p_old );

    p_map1
        [in/out] Pointer to the first of two cl_map_t structures whose 
        differences to compute.

    p_map2
        [in/out] Pointer to the second of two cl_map_t structures whose 
        differences to compute.

    p_new
        [out] Pointer to an empty cl_map_t structure that contains the items
        unique to p_map2 upon return from the function.

    p_old
        [out] Pointer to an empty cl_map_t structure that contains the items 
        unique to p_map1 upon return from the function.

    CL_SUCCESS if the operation succeeded.

    CL_INSUFFICIENT_MEMORY if there was not enough memory for the operation
    to succeed.

    Items are evaluated based on their keys.  Items that exist in both
    p_map1 and p_map2 remain in their respective maps.  Items that
    exist only p_map1 are moved to p_old.  Likewise, items that exist only
    in p_map2 are moved to p_new.  This function can be usefull in evaluating
    changes between two maps.

    Both maps pointed to by p_new and p_old must be empty on input.

    Upon failure, all input maps are restored to their original state.

    Map, cl_map_merge

Component Library: Map/cl_map_destroy

    cl_map_destroy

    The cl_map_destroy function destroys a map.

void
cl_map_destroy(
    IN  cl_map_t* const p_map );

    p_map
        [in] Pointer to a map to destroy.

    This function does not return a value.

    Performs any necessary cleanup of the specified map. Further
    operations should not be attempted on the map. cl_map_destroy does
    not affect any of the objects stored in the map.
    This function should only be called after a call to cl_map_construct.

    In debug builds, cl_map_destroy asserts that the map is empty.

    Map, cl_map_construct, cl_map_init

Component Library: Map/cl_map_end

    cl_map_end

    The cl_map_end function returns the iterator for the end of a map.

 const cl_map_iterator_t
cl_map_end(
    IN  const cl_map_t* const   p_map ;

    p_map
        [in] Pointer to a cl_map_t structure whose end to return.

    Iterator for the end of the map.

    cl_map_end is useful for determining the validity of map items returned
    by cl_map_head, cl_map_tail, cl_map_next, cl_map_prev.  If the iterator
    by any of these functions compares to the end, the end of the map was
    encoutered.
    When using cl_map_head or cl_map_tail, this condition indicates that
    the map is empty.

    Map, cl_qmap_head, cl_qmap_tail, cl_qmap_next, cl_qmap_prev

Component Library: Map/cl_map_get

    cl_map_get

    The cl_map_get function returns the object associated with a key.

void*
cl_map_get(
    IN  const cl_map_t* const   p_map,
    IN  const uint64_t          key );

    p_map
        [in] Pointer to a map from which to retrieve the object with
        the specified key.

    key
        [in] Key value used to search for the desired object.

    Pointer to the object with the desired key value.

    NULL if there was no item with the desired key value stored in
    the map.

    cl_map_get does not remove the item from the map.

    Map, cl_map_remove

Component Library: Map/cl_map_head

    cl_map_head

    The cl_map_head function returns the map item with the lowest key
    value stored in a map.

 cl_map_iterator_t
cl_map_head(
    IN  const cl_map_t* const   p_map ;

    p_map
        [in] Pointer to a map whose item with the lowest key is returned.

    Iterator for the object with the lowest key in the map.

    Iterator for the map end if the map was empty.

    cl_map_head does not remove the object from the map.

    Map, cl_map_tail, cl_map_next, cl_map_prev, cl_map_end

Component Library: Map/cl_map_init

    cl_map_init

    The cl_map_init function initialized a map for use.

cl_status_t
cl_map_init(
    IN  cl_map_t* const p_map,
    IN  const size_t    min_items );

    p_map
        [in] Pointer to a cl_map_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 map was initialized successfully.

    Allows calling map manipulation functions.

    Map, cl_map_destroy, cl_map_insert, cl_map_remove

Component Library: Map/cl_map_insert

    cl_map_insert

    The cl_map_insert function inserts a map item into a map.

void*
cl_map_insert(
    IN  cl_map_t* const     p_map,
    IN  const uint64_t      key,
    IN  const void* const   p_object );

    p_map
        [in] Pointer to a map into which to add the item.

    key
        [in] Value to associate with the object.

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

    Pointer to the object in the map with the specified key after the call
    completes.

    NULL if there was not enough memory to insert the desired item.

    Insertion operations may cause the map to rebalance.

    If the map already contains an object already with the specified key,
    that object will not be replaced and the pointer to that object is
    returned.

    Map, cl_map_remove, cl_map_item_t

Component Library: Map/cl_map_iterator_t

    cl_map_iterator_t

    Iterator type used to walk a map.

typedef const cl_map_item_t *cl_map_iterator_t;

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

    Map, cl_map_head, cl_map_tail, cl_map_next, cl_map_prev, cl_map_key

Component Library: Map/cl_map_key

    cl_map_key

    The cl_map_key function retrieves the key value of a map item.

 uint64_t
cl_map_key(
    IN  const cl_map_iterator_t itor ;

    itor
        [in] Iterator for the item whose key to return.

    Returns the 64-bit key value for the specified iterator.

    The iterator specified by the itor parameter must have been retrived by
    a previous call to cl_map_head, cl_map_tail, cl_map_next, or cl_map_prev.

    The key value is set in a call to cl_map_insert.

    Map, cl_map_insert, cl_map_head, cl_map_tail, cl_map_next, cl_map_prev

Component Library: Map/cl_map_merge

    cl_map_merge

    The cl_map_merge function moves all items from one map to another, 
    excluding duplicates.

cl_status_t
cl_map_merge(
    OUT     cl_map_t* const p_dest_map,
    IN OUT  cl_map_t* const p_src_map );

    p_dest_map
        [out] Pointer to a cl_map_t structure to which items should be added.

    p_src_map
        [in/out] Pointer to a cl_map_t structure whose items to add 
        to p_dest_map.

    CL_SUCCESS if the operation succeeded.

    CL_INSUFFICIENT_MEMORY if there was not enough memory for the operation
    to succeed.

    Items are evaluated based on their keys only.

    Upon return from cl_map_merge, the map referenced by p_src_map contains 
    all duplicate items.

    Map, cl_map_delta

Component Library: Map/cl_map_next

    cl_map_next

    The cl_map_next function returns the map item with the next higher
    key value than a specified map item.

 cl_map_iterator_t
cl_map_next(
    IN  const cl_map_iterator_t itor ;

    itor
        [in] Iterator for an object in a map whose successor to return.

    Iterator for the object with the next higher key value in a map.

    Iterator for the map end if the specified object was the last item in
    the map.

    The iterator must have been retrieved by a previous call to cl_map_head,
    cl_map_tail, cl_map_next, or cl_map_prev.

    Map, cl_map_head, cl_map_tail, cl_map_prev, cl_map_end

Component Library: Map/cl_map_obj

    cl_map_obj

    The cl_map_obj function returns the object associated with an iterator.

 void*
cl_map_obj(
    IN  const cl_map_iterator_t itor ;

    itor
        [in] Iterator whose object to return.

    Returns the value of the object pointer associated with the iterator.

    The iterator must have been retrieved by a previous call to cl_map_head,
    cl_map_tail, cl_map_next, or cl_map_prev.

    Map, cl_map_head, cl_map_tail, cl_map_next, cl_map_prev

Component Library: Map/cl_map_prev

    cl_map_prev

    The cl_map_prev function returns the map item with the next lower
    key value than a precified map item.

 cl_map_iterator_t
cl_map_prev(
    IN  const cl_map_iterator_t itor ;

    itor
        [in] Iterator for an object in a map whose predecessor to return.

    Iterator for the object with the next lower key value in a map.

    Iterator for the map end if the specified object was the first item in
    the map.

    The iterator must have been retrieved by a previous call to cl_map_head,
    cl_map_tail, cl_map_next, or cl_map_prev.

    Map, cl_map_head, cl_map_tail, cl_map_next, cl_map_end

Component Library: Map/cl_map_remove

    cl_map_remove

    The cl_map_remove function removes the map item with the specified key
    from a map.

void*
cl_map_remove(
    IN  cl_map_t* const p_map,
    IN  const uint64_t  key );

    p_map
        [in] Pointer to a cl_map_t structure from which to remove the item
        with the specified key.

    key
        [in] Key value used to search for the object to remove.

    Pointer to the object associated with the specified key if
    it was found and removed.

    NULL if no object with the specified key exists in the map.

    Map, cl_map_remove_item, cl_map_remove_all, cl_map_insert

Component Library: Map/cl_map_remove_all

    cl_map_remove_all

    The cl_map_remove_all function removes all objects from a map,
    leaving it empty.

void
cl_map_remove_all(
    IN  cl_map_t* const p_map );

    p_map
        [in] Pointer to a map to empty.

    This function does not return a value.

    Map, cl_map_remove, cl_map_remove_item

Component Library: Map/cl_map_remove_item

    cl_map_remove_item

    The cl_map_remove_item function removes the specified map item
    from a map.

void
cl_map_remove_item(
    IN  cl_map_t* const         p_map,
    IN  const cl_map_iterator_t itor );

    p_map
        [in] Pointer to a map from which to remove the object associated with
        the specified iterator.

    itor
        [in] Iterator for an object to remove from its map.

    This function does not return a value.

    Removes the object associated with the specifid iterator from its map.

    The specified iterator is no longer valid after the call completes.

    The iterator must have been retrieved by a previous call to cl_map_head,
    cl_map_tail, cl_map_next, or cl_map_prev.

    Map, cl_map_remove, cl_map_remove_all, cl_map_insert, cl_map_head,
    cl_map_tail, cl_map_next, cl_map_prev

Component Library: Map/cl_map_t

    cl_map_t

    Quick map structure.

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

typedef struct _cl_map
{
    cl_qmap_t   qmap;
    cl_qpool_t  pool;

} cl_map_t;

    qmap
        Quick map object that maintains the map.

    pool
        Pool of cl_map_obj_t structures used to store user objects
        in the map.

    Map, cl_map_obj_t

Component Library: Map/cl_map_tail

    cl_map_tail

    The cl_map_tail function returns the map item with the highest key
    value stored in a map.

 cl_map_iterator_t
cl_map_tail(
    IN  const cl_map_t* const   p_map ;

    p_map
        [in] Pointer to a map whose item with the highest key
        is returned.

    Iterator for the object with the highest key in the map.

    Iterator for the map end if the map was empty.

    cl_map_end does no remove the object from the map.

    Map, cl_map_head, cl_map_next, cl_map_prev, cl_map_end