Generated from ./inc/complib/cl_qlist.h with ROBODoc v4.99.17 on Sun Mar 04 2007 18:17:51

[Modules] Component Library/Quick List

[top][parent][index]

NAME

       Quick List

DESCRIPTION

       Quick list implements a doubly linked that stores user provided
       cl_list_item_t structures.
       Quick list does not allocate any memory, and can therefore not fail any
       operations.  Quick list can therefore be useful in minimizing the error
       paths in code.

       Quick list is not thread safe, and users must provide serialization when
       adding and removing items from the list. Note that it is possible to
       walk a quick list while simultaneously adding to it.

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

SEE ALSO

       Structures:
               cl_qlist_t, cl_list_item_t, cl_list_obj_t

       Callbacks:
               cl_pfn_qlist_apply_t, cl_pfn_qlist_find_t

       Item Manipulation:
               cl_qlist_set_obj, cl_qlist_obj

       Initialization:
               cl_qlist_init

       Iteration:
               cl_qlist_next, cl_qlist_prev, cl_qlist_head, cl_qlist_tail,
               cl_qlist_end

       Manipulation:
               cl_qlist_insert_head, cl_qlist_insert_tail,
               cl_qlist_insert_list_head, cl_qlist_insert_list_tail,
               cl_qlist_insert_array_head, cl_qlist_insert_array_tail,
               cl_qlist_insert_prev, cl_qlist_insert_next,
               cl_qlist_remove_head, cl_qlist_remove_tail,
               cl_qlist_remove_item, cl_qlist_remove_all

       Search:
               cl_is_item_in_qlist, cl_qlist_find_next, cl_qlist_find_prev,
               cl_qlist_find_from_head, cl_qlist_find_from_tail
               cl_qlist_apply_func, cl_qlist_move_items

       Attributes:
               cl_qlist_count, cl_is_qlist_empty

[Functions] Component Library: Quick List/cl_is_item_in_qlist

[top][index]

NAME

       cl_is_item_in_qlist

DESCRIPTION

       The cl_is_item_in_qlist function checks for the presence of a
       list item in a quick list.

SYNOPSIS

CL_EXPORT boolean_t CL_API
cl_is_item_in_qlist(
        IN      const cl_qlist_t* const         p_list,
        IN      const cl_list_item_t* const     p_list_item );

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

       p_list_item
               [in] Pointer to the cl_list_item_t to find.

 RETURN VALUES
       TRUE if the list item was found in the quick list.

       FALSE otherwise.

SEE ALSO

       Quick List, cl_qlist_remove_item, cl_list_item_t

[Functions] Component Library: Quick List/cl_is_qlist_empty

[top][index]

NAME

       cl_is_qlist_empty

DESCRIPTION

       The cl_is_qlist_empty function returns whether a quick list is empty.

SYNOPSIS

CL_INLINE boolean_t CL_API
cl_is_qlist_empty(
        IN      const cl_qlist_t* const p_list )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        return( !cl_qlist_count( p_list ) );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

 RETURN VALUES
       TRUE if the specified quick list is empty.

       FALSE otherwise.

SEE ALSO

       Quick List, cl_qlist_count, cl_qlist_remove_all

[Structures] Component Library: Quick List/cl_list_item_t

[top][index]

NAME

       cl_list_item_t

DESCRIPTION

       The cl_list_item_t structure is used by lists to store objects.

SYNOPSIS

typedef struct _cl_list_item
{
        struct _cl_list_item    *p_next;
        struct _cl_list_item    *p_prev;
#ifdef _DEBUG_
        struct _cl_qlist                *p_list;
#endif

} cl_list_item_t;

FIELDS

       p_next
               Used internally by the list. Users should not use this field.

       p_prev
               Used internally by the list. Users should not use this field.

SEE ALSO

       Quick List

[Structures] Component Library: Quick List/cl_list_obj_t

[top][index]

NAME

       cl_list_obj_t

DESCRIPTION

       The cl_list_obj_t structure is used by lists to store objects.

SYNOPSIS

typedef struct _cl_list_obj
{
        cl_list_item_t          list_item;
        const void                      *p_object;              /* User's context */

} cl_list_obj_t;

FIELDS

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

       p_object
               User defined context. Users should not access this field directly.
               Use cl_qlist_set_obj and cl_qlist_obj to set and retrieve the value
               of this field.

NOTES

       Users can use the cl_qlist_set_obj and cl_qlist_obj functions to store
       and retrieve context information in the list item.

SEE ALSO

       Quick List, cl_qlist_set_obj, cl_qlist_obj, cl_list_item_t

[Definitions] Component Library: Quick List/cl_pfn_qlist_apply_t

[top][index]

NAME

       cl_pfn_qlist_apply_t

DESCRIPTION

       The cl_pfn_qlist_apply_t function type defines the prototype for functions
       used to iterate items in a quick list.

SYNOPSIS

typedef void
(CL_API *cl_pfn_qlist_apply_t)(
        IN      cl_list_item_t* const   p_list_item,
        IN      void*                                   context );

PARAMETERS

       p_list_item
               [in] Pointer to a cl_list_item_t structure.

       context
               [in] Value passed to the callback function.

RETURN VALUE

       This function does not return a value.

NOTES

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

SEE ALSO

       Quick List, cl_qlist_apply_func

[Definitions] Component Library: Quick List/cl_pfn_qlist_find_t

[top][index]

NAME

       cl_pfn_qlist_find_t

DESCRIPTION

       The cl_pfn_qlist_find_t function type defines the prototype for functions
       used to find items in a quick list.

SYNOPSIS

typedef cl_status_t
(CL_API *cl_pfn_qlist_find_t)(
        IN      const cl_list_item_t* const     p_list_item,
        IN      void*                                           context );

PARAMETERS

       p_list_item
               [in] Pointer to a cl_list_item_t.

       context
               [in] Value passed to the callback function.

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

       Return CL_NOT_FOUND to continue list iteration.

NOTES

       This function type is provided as function prototype reference for the
       function provided by users as a parameter to the cl_qlist_find_from_head,
       cl_qlist_find_from_tail, cl_qlist_find_next, and cl_qlist_find_prev
       functions.

SEE ALSO

       Quick List, cl_qlist_find_from_head, cl_qlist_find_from_tail,
       cl_qlist_find_next, cl_qlist_find_prev

[Functions] Component Library: Quick List/cl_qlist_apply_func

[top][index]

NAME

       cl_qlist_apply_func

DESCRIPTION

       The cl_qlist_apply_func function executes a specified function
       for every list item stored in a quick list.

SYNOPSIS

CL_EXPORT void CL_API
cl_qlist_apply_func(
        IN      const cl_qlist_t* const p_list,
        IN      cl_pfn_qlist_apply_t    pfn_func,
        IN      const void* const               context );

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

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

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

RETURN VALUE

       This function does not return a value.

NOTES

       The function provided must not perform any list operations, as these
       would corrupt the quick list.

SEE ALSO

       Quick List, cl_qlist_find_from_head, cl_qlist_find_from_tail,
       cl_qlist_move_items, cl_pfn_qlist_apply_t

[Functions] Component Library: Quick List/cl_qlist_count

[top][index]

NAME

       cl_qlist_count

DESCRIPTION

       The cl_qlist_count function returns the number of list items stored
       in a quick list.

SYNOPSIS

CL_INLINE size_t CL_API
cl_qlist_count(
        IN      const cl_qlist_t* const p_list )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        return( p_list->count );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

RETURN VALUE

       Number of items in the list.  This function iterates though the quick
       list to count the items.

SEE ALSO

       Quick List, cl_is_qlist_empty

[Functions] Component Library: Quick List/cl_qlist_end

[top][index]

NAME

       cl_qlist_end

DESCRIPTION

       The cl_qlist_end function returns the end of a quick list.

SYNOPSIS

CL_INLINE const cl_list_item_t* const CL_API
cl_qlist_end(
        IN      const cl_qlist_t* const p_list )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        return( &p_list->end );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

RETURN VALUE

       Pointer to the end of the list.

NOTES

       cl_qlist_end is useful for determining the validity of list items returned
       by cl_qlist_head, cl_qlist_tail, cl_qlist_next, cl_qlist_prev, as well as
       the cl_qlist_find functions.  If the list item pointer returned by any of
       these functions compares to the end, the end of the list was encoutered.
       When using cl_qlist_head or cl_qlist_tail, this condition indicates that
       the list is empty.

SEE ALSO

       Quick List, cl_qlist_head, cl_qlist_tail, cl_qlist_next, cl_qlist_prev,
       cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_find_from_head

[top][index]

NAME

       cl_qlist_find_from_head

DESCRIPTION

       The cl_qlist_find_from_head function invokes a specified function to
       search for an item, starting at the head of a quick list.

SYNOPSIS

CL_INLINE cl_list_item_t* CL_API
cl_qlist_find_from_head(
        IN      const cl_qlist_t* const p_list,
        IN      cl_pfn_qlist_find_t             pfn_func,
        IN      const void* const               context )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );
        /* CL_ASSERT that a find function is provided. */
        CL_ASSERT( pfn_func );

        return( cl_qlist_find_next( p_list, cl_qlist_end( p_list ), pfn_func,
                context ) );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

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

       context
               [in] Value to pass to the callback functions to provide context if a
               callback function is provided, or value compared to the quick list's
               list items.

 Returns:
       Pointer to the list item, if found.

       Pointer to the list end otherwise

NOTES

       cl_qlist_find_from_head does not remove list items from the list.
       The list item is returned when the function specified by the pfn_func
       parameter returns CL_SUCCESS.

       The function provided by the pfn_func parameter must not perform any list
       operations, as these would corrupt the list.

SEE ALSO

       Quick List, cl_qlist_find_from_tail, cl_qlist_find_next, cl_qlist_find_prev,
       cl_qlist_end, cl_qlist_apply_func, cl_qlist_move_items, cl_list_item_t,
       cl_pfn_qlist_find_t

[Functions] Component Library: Quick List/cl_qlist_find_from_tail

[top][index]

NAME

       cl_qlist_find_from_tail

DESCRIPTION

       The cl_qlist_find_from_tail function invokes a specified function to
       search for an item, starting at the tail of a quick list.

SYNOPSIS

CL_INLINE cl_list_item_t* CL_API
cl_qlist_find_from_tail(
        IN      const cl_qlist_t* const p_list,
        IN      cl_pfn_qlist_find_t             pfn_func,
        IN      const void* const               context )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );
        /* CL_ASSERT that a find function is provided. */
        CL_ASSERT( pfn_func );

        return( cl_qlist_find_prev( p_list, cl_qlist_end( p_list ), pfn_func,
                context ) );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

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

       context
               [in] Value to pass to the callback functions to provide context if a
               callback function is provided, or value compared to the quick list's
               list items.

 Returns:
       Pointer to the list item, if found.

       Pointer to the list end otherwise

NOTES

       cl_qlist_find_from_tail does not remove list items from the list.
       The list item is returned when the function specified by the pfn_func
       parameter returns CL_SUCCESS.

       The function provided by the pfn_func parameter must not perform any list
       operations, as these would corrupt the list.

SEE ALSO

       Quick List, cl_qlist_find_from_head, cl_qlist_find_next, cl_qlist_find_prev,
       cl_qlist_apply_func, cl_qlist_end, cl_qlist_move_items, cl_list_item_t,
       cl_pfn_qlist_find_t

[Functions] Component Library: Quick List/cl_qlist_find_next

[top][index]

NAME

       cl_qlist_find_next

DESCRIPTION

       The cl_qlist_find_next function invokes a specified function to
       search for an item, starting from a given list item.

SYNOPSIS

CL_EXPORT cl_list_item_t* CL_API
cl_qlist_find_next(
        IN      const cl_qlist_t* const         p_list,
        IN      const cl_list_item_t* const     p_list_item,
        IN      cl_pfn_qlist_find_t                     pfn_func,
        IN      const void* const                       context );

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure in which to search.

       p_list_item
               [in] Pointer to a cl_list_item_t structure from which to start the search.

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

       context
               [in] Value to pass to the callback functions to provide context if a
               callback function is provided, or value compared to the quick list's
               list items.

 Returns:
       Pointer to the list item, if found.

       p_list_item if not found.

NOTES

       cl_qlist_find_next does not remove list items from the list.
       The list item is returned when the function specified by the pfn_func
       parameter returns CL_SUCCESS.  The list item from which the search starts is
       excluded from the search.

       The function provided by the pfn_func must not perform any list operations,
       as these would corrupt the list.

SEE ALSO

       Quick List, cl_qlist_find_prev, cl_qlist_find_from_head,
       cl_qlist_find_from_tail, cl_qlist_end, cl_qlist_apply_func,
       cl_qlist_move_items, cl_list_item_t, cl_pfn_qlist_find_t

[Functions] Component Library: Quick List/cl_qlist_find_prev

[top][index]

NAME

       cl_qlist_find_prev

DESCRIPTION

       The cl_qlist_find_prev function invokes a specified function to
       search backward for an item, starting from a given list item.

SYNOPSIS

CL_EXPORT cl_list_item_t* CL_API
cl_qlist_find_prev(
        IN      const cl_qlist_t* const         p_list,
        IN      const cl_list_item_t* const     p_list_item,
        IN      cl_pfn_qlist_find_t                     pfn_func,
        IN      const void* const                       context );

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure in which to search.

       p_list_item
               [in] Pointer to a cl_list_item_t structure from which to start the search.

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

       context
               [in] Value to pass to the callback functions to provide context if a
               callback function is provided, or value compared to the quick list's
               list items.

 Returns:
       Pointer to the list item, if found.

       p_list_item if not found.

NOTES

       cl_qlist_find_prev does not remove list items from the list.
       The list item is returned when the function specified by the pfn_func
       parameter returns CL_SUCCESS.  The list item from which the search starts is
       excluded from the search.

       The function provided by the pfn_func must not perform any list operations,
       as these would corrupt the list.

SEE ALSO

       Quick List, cl_qlist_find_next, cl_qlist_find_from_head,
       cl_qlist_find_from_tail, cl_qlist_end, cl_qlist_apply_func,
       cl_qlist_move_items, cl_list_item_t, cl_pfn_qlist_find_t

[Functions] Component Library: Quick List/cl_qlist_head

[top][index]

NAME

       cl_qlist_head

DESCRIPTION

       The cl_qlist_head function returns the list item at
       the head of a quick list.

SYNOPSIS

CL_INLINE cl_list_item_t* CL_API
cl_qlist_head(
        IN      const cl_qlist_t* const p_list )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        return( cl_qlist_next( &p_list->end ) );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

 RETURN VALUES
       Pointer to the list item at the head of the quick list.

       Pointer to the list end if the list was empty.

NOTES

       cl_qlist_head does not remove the item from the list.

SEE ALSO

       Quick List, cl_qlist_tail, cl_qlist_next, cl_qlist_prev, cl_qlist_end,
       cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_init

[top][index]

NAME

       cl_qlist_init

DESCRIPTION

       The cl_qlist_init function initializes a quick list.

SYNOPSIS

CL_INLINE void CL_API
cl_qlist_init(
        IN      cl_qlist_t* const       p_list )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );

        p_list->state = CL_INITIALIZED;

        /* Reset the quick list data structure. */
        __cl_qlist_reset( p_list );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure to initialize.

 RETURN VALUES
       This function does not return a value.

NOTES

       Allows calling quick list manipulation functions.

SEE ALSO

       Quick List, cl_qlist_insert_head, cl_qlist_insert_tail,
       cl_qlist_remove_head, cl_qlist_remove_tail

[Functions] Component Library: Quick List/cl_qlist_insert_array_head

[top][index]

NAME

       cl_qlist_insert_array_head

DESCRIPTION

       The cl_qlist_insert_array_head function inserts an array of list items
       at the head of a quick list.

SYNOPSIS

CL_EXPORT void CL_API
cl_qlist_insert_array_head(
        IN      cl_qlist_t* const               p_list,
        IN      cl_list_item_t* const   p_array,
        IN      size_t                                  item_count,
        IN      const size_t                    item_size );

PARAMETERS

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

       p_array
               [in] Pointer to the first list item in an array of cl_list_item_t
               structures.

       item_count
               [in] Number of cl_list_item_t structures in the array.

       item_size
               [in] Size of the items added to the list. This is the stride in the
               array from one cl_list_item_t structure to the next.

RETURN VALUE

       This function does not return a value.

NOTES

       Inserts all the list items in the array specified by the p_array parameter
       to the head of the quick list specified by the p_list parameter,
       preserving ordering of the list items.

       The array pointer passed into the function points to the cl_list_item_t
       in the first element of the caller's element array.  There is no
       restriction on where the element is stored in the parent structure.

SEE ALSO

       Quick List, cl_qlist_insert_array_tail, cl_qlist_insert_head,
       cl_qlist_insert_tail, cl_qlist_insert_list_head, cl_qlist_insert_list_tail,
       cl_qlist_insert_prev, cl_qlist_insert_next, cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_insert_array_tail

[top][index]

NAME

       cl_qlist_insert_array_tail

DESCRIPTION

       The cl_qlist_insert_array_tail function inserts an array of list items
       at the tail of a quick list.

SYNOPSIS

CL_EXPORT void CL_API
cl_qlist_insert_array_tail(
        IN      cl_qlist_t* const               p_list,
        IN      cl_list_item_t* const   p_array,
        IN      size_t                                  item_count,
        IN      const size_t                    item_size);

PARAMETERS

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

       p_array
               [in] Pointer to the first list item in an array of cl_list_item_t
               structures.

       item_count
               [in] Number of cl_list_item_t structures in the array.

       item_size
               [in] Size of the items added to the list. This is the stride in the
               array from one cl_list_item_t structure to the next.

RETURN VALUE

       This function does not return a value.

NOTES

       Inserts all the list items in the array specified by the p_array parameter
       to the tail of the quick list specified by the p_list parameter,
       preserving ordering of the list items.

       The array pointer passed into the function points to the cl_list_item_t
       in the first element of the caller's element array.  There is no
       restriction on where the element is stored in the parent structure.

SEE ALSO

       Quick List, cl_qlist_insert_array_head, cl_qlist_insert_head,
       cl_qlist_insert_tail, cl_qlist_insert_list_head, cl_qlist_insert_list_tail,
       cl_qlist_insert_prev, cl_qlist_insert_next, cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_insert_head

[top][index]

NAME

       cl_qlist_insert_head

DESCRIPTION

       The cl_qlist_insert_head function inserts a list item at the
       head of a quick list.

SYNOPSIS

CL_INLINE void CL_API
cl_qlist_insert_head(
        IN      cl_qlist_t* const               p_list,
        IN      cl_list_item_t* const   p_list_item )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list_item );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        /*
         * The list item must not already be part of the list.  Note that this
         * assertion may fail if an uninitialized list item happens to have its
         * list pointer equal to the specified list.  The chances of this
         * happening are acceptable in light of the value of this check.
         */
        CL_ASSERT( p_list_item->p_list != p_list );

#if defined( _DEBUG_ )
        p_list_item->p_list = p_list;
#endif

        /* Insert before the head. */
        __cl_primitive_insert( cl_qlist_head( p_list ), p_list_item );

        p_list->count++;
}

PARAMETERS

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

       p_list_item
               [in] Pointer to a cl_list_item_t structure to add.

RETURN VALUE

       This function does not return a value.

NOTES

       In debug builds, cl_qlist_insert_head asserts that the specified list item
       is not already in the list.

SEE ALSO

       Quick List, cl_qlist_insert_tail, cl_qlist_insert_list_head,
       cl_qlist_insert_list_tail, cl_qlist_insert_array_head,
       cl_qlist_insert_array_tail, cl_qlist_insert_prev, cl_qlist_insert_next,
       cl_qlist_remove_head, cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_insert_list_head

[top][index]

NAME

       cl_qlist_insert_list_head

DESCRIPTION

       The cl_qlist_insert_list_head function merges two quick lists by
       inserting one at the head of the other.

SYNOPSIS

CL_EXPORT void CL_API
cl_qlist_insert_list_head(
        IN      cl_qlist_t* const       p_dest_list,
        IN      cl_qlist_t* const       p_src_list );

PARAMETERS

       p_dest_list
               [in] Pointer to destination quicklist object.

       p_src_list
               [in] Pointer to quicklist to add.

RETURN VALUE

       This function does not return a value.

NOTES

       Inserts all list items in the source list to the head of the
       destination list. The ordering of the list items is preserved.

       The list pointed to by the p_src_list parameter is empty when
       the call returns.

SEE ALSO

       Quick List, cl_qlist_insert_list_tail, cl_qlist_insert_head,
       cl_qlist_insert_tail, cl_qlist_insert_array_head,
       cl_qlist_insert_array_tail, cl_qlist_insert_prev, cl_qlist_insert_next,
       cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_insert_list_tail

[top][index]

NAME

       cl_qlist_insert_list_tail

DESCRIPTION

       The cl_qlist_insert_list_tail function merges two quick lists by
       inserting one at the tail of the other.

SYNOPSIS

CL_EXPORT void CL_API
cl_qlist_insert_list_tail(
        IN      cl_qlist_t* const       p_dest_list,
        IN      cl_qlist_t* const       p_src_list );

PARAMETERS

       p_dest_list
               [in] Pointer to destination quicklist object

       p_src_list
               [in] Pointer to quicklist to add

RETURN VALUE

       This function does not return a value.

NOTES

       Inserts all list items in the source list to the tail of the
       destination list. The ordering of the list items is preserved.

       The list pointed to by the p_src_list parameter is empty when
       the call returns.

SEE ALSO

       Quick List, cl_qlist_insert_list_head, cl_qlist_insert_head,
       cl_qlist_insert_tail, cl_qlist_insert_array_head,
       cl_qlist_insert_array_tail, cl_qlist_insert_prev, cl_qlist_insert_next,
       cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_insert_next

[top][index]

NAME

       cl_qlist_insert_next

DESCRIPTION

       The cl_qlist_insert_next function inserts a list item after a specified
       list item in a quick list.

SYNOPSIS

CL_INLINE void CL_API
cl_qlist_insert_next(
        IN      cl_qlist_t* const               p_list,
        IN      cl_list_item_t* const   p_list_item,
        IN      cl_list_item_t* const   p_new_item )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list_item );
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_new_item );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        /*
         * The list item must not already be part of the list.  Note that this
         * assertion may fail if an uninitialized list item happens to have its
         * list pointer equal to the specified list.  The chances of this
         * happening are acceptable in light of the value of this check.
         */
        CL_ASSERT( p_new_item->p_list != p_list );

#if defined( _DEBUG_ )
        p_new_item->p_list = p_list;
#endif

        __cl_primitive_insert( cl_qlist_next( p_list_item ), p_new_item );

        p_list->count++;
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure into which to add the new item.

       p_list_item
               [in] Pointer to a cl_list_item_t structure.

       p_new_item
               [in] Pointer to a cl_list_item_t structure to add to the quick list.

RETURN VALUE

       This function does not return a value.

NOTES

       Inserts the new list item after the list item specified by p_list_item.
       The list item specified by p_list_item must be in the quick list.

SEE ALSO

       Quick List, cl_qlist_insert_prev, cl_qlist_insert_head,
       cl_qlist_insert_tail, cl_qlist_insert_list_head, cl_qlist_insert_list_tail,
       cl_qlist_insert_array_head, cl_qlist_insert_array_tail, cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_insert_prev

[top][index]

NAME

       cl_qlist_insert_prev

DESCRIPTION

       The cl_qlist_insert_prev function inserts a list item before a
       specified list item in a quick list.

SYNOPSIS

CL_INLINE void CL_API
cl_qlist_insert_prev(
        IN      cl_qlist_t* const               p_list,
        IN      cl_list_item_t* const   p_list_item,
        IN      cl_list_item_t* const   p_new_item )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list_item );
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_new_item );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        /*
         * The list item must not already be part of the list.  Note that this
         * assertion may fail if an uninitialized list item happens to have its
         * list pointer equal to the specified list.  The chances of this
         * happening are acceptable in light of the value of this check.
         */
        CL_ASSERT( p_new_item->p_list != p_list );

#if defined( _DEBUG_ )
        p_new_item->p_list = p_list;
#endif

        __cl_primitive_insert( p_list_item, p_new_item );

        p_list->count++;
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure into which to add the new item.

       p_list_item
               [in] Pointer to a cl_list_item_t structure.

       p_new_item
               [in] Pointer to a cl_list_item_t structure to add to the quick list.

RETURN VALUE

       This function does not return a value.

NOTES

       Inserts the new list item before the list item specified by p_list_item.

SEE ALSO

       Quick List, cl_qlist_insert_next, cl_qlist_insert_head,
       cl_qlist_insert_tail, cl_qlist_insert_list_head, cl_qlist_insert_list_tail,
       cl_qlist_insert_array_head, cl_qlist_insert_array_tail, cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_insert_tail

[top][index]

NAME

       cl_qlist_insert_tail

DESCRIPTION

       The cl_qlist_insert_tail function inserts a list item at the tail
       of a quick list.

SYNOPSIS

CL_INLINE void CL_API
cl_qlist_insert_tail(
        IN      cl_qlist_t* const               p_list,
        IN      cl_list_item_t* const   p_list_item )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list_item );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        /*
         * The list item must not already be part of the list.  Note that this
         * assertion may fail if an uninitialized list item happens to have its
         * list pointer equal to the specified list.  The chances of this
         * happening are acceptable in light of the value of this check.
         */
        CL_ASSERT( p_list_item->p_list != p_list );

#if defined( _DEBUG_ )
        p_list_item->p_list = p_list;
#endif

        /*
         * Put the new element in front of the end which is the same
         * as being at the tail
         */
        __cl_primitive_insert( &p_list->end, p_list_item );

        p_list->count++;
}

PARAMETERS

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

       p_list_item
               [in] Pointer to cl_list_item_t structure to add.

RETURN VALUE

       This function does not return a value.

NOTES

       In debug builds, cl_qlist_insert_tail asserts that the specified list item
       is not already in the list.

SEE ALSO

       Quick List, cl_qlist_insert_head, cl_qlist_insert_list_head,
       cl_qlist_insert_list_tail, cl_qlist_insert_array_head,
       cl_qlist_insert_array_tail, cl_qlist_insert_prev, cl_qlist_insert_next,
       cl_qlist_remove_tail, cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_move_items

[top][index]

NAME

       cl_qlist_move_items

DESCRIPTION

       The cl_qlist_move_items function moves list items from one list to
       another based on the return value of a user supplied function.

SYNOPSIS

CL_EXPORT void CL_API
cl_qlist_move_items(
        IN      cl_qlist_t* const       p_src_list,
        IN      cl_qlist_t* const       p_dest_list,
        IN      cl_pfn_qlist_find_t     pfn_func,
        IN      const void* const       context );

PARAMETERS

       p_src_list
               [in] Pointer to a cl_qlist_t structure from which
               list items are removed.

       p_dest_list
               [in] Pointer to a cl_qlist_t structure to which the source
               list items are added.

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

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

RETURN VALUE

       This function does not return a value.

NOTES

       If the function specified by the pfn_func parameter returns CL_SUCCESS,
       the related list item is removed from p_src_list and inserted at the tail
       of the p_dest_list.

       The cl_qlist_move_items function continues iterating through p_src_list
       from the last item moved, allowing multiple items to be located and moved
       in a single list iteration.

       The function specified by pfn_func must not perform any list operations,
       as these would corrupt the list.

SEE ALSO

       Quick List, cl_qlist_find_from_head, cl_qlist_find_from_tail,
       cl_qlist_apply_func, cl_pfn_qlist_find_t

[Functions] Component Library: Quick List/cl_qlist_next

[top][index]

NAME

       cl_qlist_next

DESCRIPTION

       The cl_qlist_next function returns a pointer to the list item following
       a given list item in a quick list.

SYNOPSIS

CL_INLINE cl_list_item_t* CL_API
cl_qlist_next(
        IN      const cl_list_item_t* const     p_list_item )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list_item );

        /* Return the next item. */
        return( p_list_item->p_next );
}

PARAMETERS

       p_list_item
               [in] Pointer to the cl_list_item_t whose successor to return.

 Returns:
       Pointer to the list item following the list item specified by
       the p_list_item parameter in the quick list.

       Pointer to the list end if p_list_item was at the tail of the list.

SEE ALSO

       Quick List, cl_qlist_head, cl_qlist_tail, cl_qlist_prev, cl_qlist_end,
       cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_obj

[top][index]

NAME

       cl_qlist_obj

DESCRIPTION

       The cl_qlist_set_obj function returns the object stored in a list object.

SYNOPSIS

CL_INLINE void* CL_API
cl_qlist_obj(
        IN      const cl_list_obj_t* const      p_list_obj )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list_obj );

        return( (void*)p_list_obj->p_object );
}

PARAMETERS

       p_list_obj
               [in] Pointer to a cl_list_obj_t structure.

RETURN VALUE

       Returns the value of the object pointer stored in the list object.

SEE ALSO

       Quick List, cl_qlist_set_obj

[Functions] Component Library: Quick List/cl_qlist_prev

[top][index]

NAME

       cl_qlist_prev

DESCRIPTION

       The cl_qlist_prev function returns a poirter to the list item preceding
       a given list item in a quick list.

SYNOPSIS

CL_INLINE cl_list_item_t* CL_API
cl_qlist_prev(
        IN      const cl_list_item_t* const     p_list_item )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list_item );

        /* Return the previous item. */
        return( p_list_item->p_prev );
}

PARAMETERS

       p_list_item
               [in] Pointer to the cl_list_item_t whose predecessor to return.

 Returns:
       Pointer to the list item preceding the list item specified by
       the p_list_item parameter in the quick list.

       Pointer to the list end if p_list_item was at the tail of the list.

SEE ALSO

       Quick List, cl_qlist_head, cl_qlist_tail, cl_qlist_next, cl_qlist_end,
       cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_remove_all

[top][index]

NAME

       cl_qlist_remove_all

DESCRIPTION

       The cl_qlist_remove_all function removes all items from a quick list.

SYNOPSIS

CL_INLINE void CL_API
cl_qlist_remove_all(
        IN      cl_qlist_t* const       p_list )
{
#if defined( _DEBUG_ )
        cl_list_item_t  *p_list_item;

        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );
        p_list_item = cl_qlist_head( p_list );
        while( p_list_item != cl_qlist_end( p_list ) )
        {
                p_list_item = cl_qlist_next( p_list_item );
                cl_qlist_prev( p_list_item )->p_list = NULL;
        }
#endif

        __cl_qlist_reset( p_list );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

RETURN VALUE

       This function does not return a value.

SEE ALSO

       Quick List, cl_qlist_remove_head, cl_qlist_remove_tail,
       cl_qlist_remove_item, cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_remove_head

[top][index]

NAME

       cl_qlist_remove_head

DESCRIPTION

       The cl_qlist_remove_head function removes and returns the list item
       at the head of a quick list.

SYNOPSIS

CL_INLINE cl_list_item_t* CL_API
cl_qlist_remove_head(
        IN      cl_qlist_t* const       p_list )
{
        cl_list_item_t  *p_item;

        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        p_item = cl_qlist_head( p_list );
        /* CL_ASSERT that the list item is part of the list. */
        CL_ASSERT( p_item->p_list == p_list );

        if( p_item == cl_qlist_end( p_list ) )
                return( p_item );

#if defined( _DEBUG_ )
        /* Clear the item's link to the list. */
        p_item->p_list = NULL;
#endif

        __cl_primitive_remove( p_item );

        p_list->count--;

        return( p_item );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

 RETURN VALUES
       Returns a pointer to the list item formerly at the head of the quick list.

       Pointer to the list end if the list was empty.

SEE ALSO

       Quick List, cl_qlist_remove_tail, cl_qlist_remove_all, cl_qlist_remove_item,
       cl_qlist_end, cl_qlist_head, cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_remove_item

[top][index]

NAME

       cl_qlist_remove_item

DESCRIPTION

       The cl_qlist_remove_item function removes a specific list item from a quick list.

SYNOPSIS

CL_INLINE void CL_API
cl_qlist_remove_item(
        IN      cl_qlist_t* const               p_list,
        IN      cl_list_item_t* const   p_list_item )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list_item  );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );
        /* CL_ASSERT that the list item is part of the list. */
        CL_ASSERT( p_list_item->p_list == p_list );

        if( p_list_item == cl_qlist_end( p_list ) )
                return;

#if defined( _DEBUG_ )
        /* Clear the item's link to the list. */
        p_list_item->p_list = NULL;
#endif

        __cl_primitive_remove( p_list_item );

        p_list->count--;
}

PARAMETERS

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

       p_list_item
               [in] Pointer to a cl_list_item_t structure to remove.

RETURN VALUE

       This function does not return a value.

NOTES

       Removes the list item pointed to by the p_list_item parameter from
       its list.

SEE ALSO

       Quick List, cl_qlist_remove_head, cl_qlist_remove_tail, cl_qlist_remove_all,
       cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_remove_tail

[top][index]

NAME

       cl_qlist_remove_tail

DESCRIPTION

       The cl_qlist_remove_tail function removes and returns the list item
       at the tail of a quick list.

SYNOPSIS

CL_INLINE cl_list_item_t* CL_API
cl_qlist_remove_tail(
        IN      cl_qlist_t* const       p_list )
{
        cl_list_item_t  *p_item;

        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        p_item = cl_qlist_tail( p_list );
        /* CL_ASSERT that the list item is part of the list. */
        CL_ASSERT( p_item->p_list == p_list );

        if( p_item == cl_qlist_end( p_list ) )
                return( p_item );

#if defined( _DEBUG_ )
        /* Clear the item's link to the list. */
        p_item->p_list = NULL;
#endif

        __cl_primitive_remove( p_item );

        p_list->count--;

        return( p_item );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

 RETURN VALUES
       Returns a pointer to the list item formerly at the tail of the quick list.

       Pointer to the list end if the list was empty.

SEE ALSO

       Quick List, cl_qlist_remove_head, cl_qlist_remove_all, cl_qlist_remove_item,
       cl_qlist_end, cl_qlist_tail, cl_list_item_t

[Functions] Component Library: Quick List/cl_qlist_set_obj

[top][index]

NAME

       cl_qlist_set_obj

DESCRIPTION

       The cl_qlist_set_obj function sets the object stored in a list object.

SYNOPSIS

CL_INLINE void CL_API
cl_qlist_set_obj(
        IN      cl_list_obj_t* const    p_list_obj,
        IN      const void* const               p_object )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list_obj );
        p_list_obj->p_object = p_object;
}

PARAMETERS

       p_list_obj
               [in] Pointer to a cl_list_obj_t structure.

       p_object
               [in] User defined context.

RETURN VALUE

       This function does not return a value.

SEE ALSO

       Quick List, cl_qlist_obj

[Structures] Component Library: Quick List/cl_qlist_t

[top][index]

NAME

       cl_qlist_t

DESCRIPTION

       Quick list structure.

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

SYNOPSIS

typedef struct _cl_qlist
{
        cl_list_item_t  end;
        size_t                  count;
        cl_state_t              state;

} cl_qlist_t;

FIELDS

       end
               List item used to mark the end of the list.

       count
               Number of items in the list.

       state
               State of the quick list.

SEE ALSO

       Quick List

[Functions] Component Library: Quick List/cl_qlist_tail

[top][index]

NAME

       cl_qlist_tail

DESCRIPTION

       The cl_qlist_tail function returns the list item at
       the tail of a quick list.

SYNOPSIS

CL_INLINE cl_list_item_t* CL_API
cl_qlist_tail(
        IN      const cl_qlist_t* const p_list )
{
        /* CL_ASSERT that a non-null pointer is provided. */
        CL_ASSERT( p_list );
        /* CL_ASSERT that the list was initialized. */
        CL_ASSERT( p_list->state == CL_INITIALIZED );

        return( cl_qlist_prev( &p_list->end ) );
}

PARAMETERS

       p_list
               [in] Pointer to a cl_qlist_t structure.

 RETURN VALUES
       Pointer to the list item at the tail of the quick list.

       Pointer to the list end if the list was empty.

NOTES

       cl_qlist_tail does not remove the item from the list.

SEE ALSO

       Quick List, cl_qlist_head, cl_qlist_next, cl_qlist_prev, cl_qlist_end,
       cl_list_item_t