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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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