17  *        copyright notice, this list of conditions and the following
21  *        copyright notice, this list of conditions and the following
38  *	Declaration of quick list.
55 /****h* Component Library/Quick List
57 *	Quick List
60 *	Quick list implements a doubly linked that stores user provided
62 *	Quick list does not allocate any memory, and can therefore not fail any
63 *	operations.  Quick list can therefore be useful in minimizing the error
66 *	Quick list is not thread safe, and users must provide serialization when
67 *	adding and removing items from the list. Note that it is possible to
68 *	walk a quick list while simultaneously adding to it.
70 *	The Quick List functions operate on a cl_qlist_t structure which should be
107 /****s* Component Library: Quick List/cl_list_item_t
126 *		Used internally by the list. Users should not use this field.
129 *		Used internally by the list. Users should not use this field.
132 *	Quick List
139 /****s* Component Library: Quick List/cl_list_obj_t
155 *		Used internally by the list. Users should not use this field.
164 *	and retrieve context information in the list item.
167 *	Quick List, cl_qlist_set_obj, cl_qlist_obj, cl_list_item_t
170 /****s* Component Library: Quick List/cl_qlist_t
175 *	Quick list structure.
190 *		List item used to mark the end of the list.
193 *		Number of items in the list.
196 *		State of the quick list.
199 *	Quick List
202 /****d* Component Library: Quick List/cl_pfn_qlist_apply_t
208 *	used to iterate items in a quick list.
232 *	Quick List, cl_qlist_apply_func
235 /****d* Component Library: Quick List/cl_pfn_qlist_find_t
241 *	used to find items in a quick list.
257 *	Return CL_SUCCESS if the desired item was found. This stops list iteration.
259 *	Return CL_NOT_FOUND to continue list iteration.
268 *	Quick List, cl_qlist_find_from_head, cl_qlist_find_from_tail,
272 /****i* Component Library: Quick List/__cl_primitive_insert
309 /****i* Component Library: Quick List/__cl_primitive_remove
314 *	Remove an item from a list.  This is a low level routine
348  * Declaration of quick list functions
351 /****f* Component Library: Quick List/cl_qlist_set_obj
356 *	The cl_qlist_set_obj function sets the object stored in a list object.
381 *	Quick List, cl_qlist_obj
384 /****f* Component Library: Quick List/cl_qlist_obj
389 *	The cl_qlist_set_obj function returns the object stored in a list object.
407 *	Returns the value of the object pointer stored in the list object.
410 *	Quick List, cl_qlist_set_obj
426 /****f* Component Library: Quick List/cl_qlist_init
431 *	The cl_qlist_init function initializes a quick list.
442 	/* Reset the quick list data structure. */  in cl_qlist_init()
455 *	Allows calling quick list manipulation functions.
458 *	Quick List, cl_qlist_insert_head, cl_qlist_insert_tail,
462 /****f* Component Library: Quick List/cl_qlist_count
467 *	The cl_qlist_count function returns the number of list items stored
468 *	in a quick list.
476 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_count()
488 *	Number of items in the list.  This function iterates though the quick
489 *	list to count the items.
492 *	Quick List, cl_is_qlist_empty
495 /****f* Component Library: Quick List/cl_is_qlist_empty
500 *	The cl_is_qlist_empty function returns whether a quick list is empty.
508 	/* CL_ASSERT that the list was initialized. */  in cl_is_qlist_empty()
520 *	TRUE if the specified quick list is empty.
525 *	Quick List, cl_qlist_count, cl_qlist_remove_all
528 /****f* Component Library: Quick List/cl_qlist_next
533 *	The cl_qlist_next function returns a pointer to the list item following
534 *	a given list item in a quick list.
543 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_next()
556 *	Pointer to the list item following the list item specified by
557 *	the p_list_item parameter in the quick list.
559 *	Pointer to the list end if p_list_item was at the tail of the list.
562 *	Quick List, cl_qlist_head, cl_qlist_tail, cl_qlist_prev, cl_qlist_end,
566 /****f* Component Library: Quick List/cl_qlist_prev
571 *	The cl_qlist_prev function returns a poirter to the list item preceding
572 *	a given list item in a quick list.
581 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_prev()
594 *	Pointer to the list item preceding the list item specified by
595 *	the p_list_item parameter in the quick list.
597 *	Pointer to the list end if p_list_item was at the tail of the list.
600 *	Quick List, cl_qlist_head, cl_qlist_tail, cl_qlist_next, cl_qlist_end,
604 /****f* Component Library: Quick List/cl_qlist_head
609 *	The cl_qlist_head function returns the list item at
610 *	the head of a quick list.
618 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_head()
630 *	Pointer to the list item at the head of the quick list.
632 *	Pointer to the list end if the list was empty.
635 *	cl_qlist_head does not remove the item from the list.
638 *	Quick List, cl_qlist_tail, cl_qlist_next, cl_qlist_prev, cl_qlist_end,
642 /****f* Component Library: Quick List/cl_qlist_tail
647 *	The cl_qlist_tail function returns the list item at
648 *	the tail of a quick list.
656 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_tail()
668 *	Pointer to the list item at the tail of the quick list.
670 *	Pointer to the list end if the list was empty.
673 *	cl_qlist_tail does not remove the item from the list.
676 *	Quick List, cl_qlist_head, cl_qlist_next, cl_qlist_prev, cl_qlist_end,
680 /****f* Component Library: Quick List/cl_qlist_end
685 *	The cl_qlist_end function returns the end of a quick list.
694 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_end()
706 *	Pointer to the end of the list.
709 *	cl_qlist_end is useful for determining the validity of list items returned
711 *	the cl_qlist_find functions.  If the list item pointer returned by any of
712 *	these functions compares to the end, the end of the list was encoutered.
714 *	the list is empty.
717 *	Quick List, cl_qlist_head, cl_qlist_tail, cl_qlist_next, cl_qlist_prev,
721 /****f* Component Library: Quick List/cl_qlist_insert_head
726 *	The cl_qlist_insert_head function inserts a list item at the
727 *	head of a quick list.
739 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_insert_head()
743 	 * The list item must not already be part of the list.  Note that this  in cl_qlist_insert_head()
744 	 * assertion may fail if an uninitialized list item happens to have its  in cl_qlist_insert_head()
745 	 * list pointer equal to the specified list.  The chances of this  in cl_qlist_insert_head()
772 *	In debug builds, cl_qlist_insert_head asserts that the specified list item
773 *	is not already in the list.
776 *	Quick List, cl_qlist_insert_tail, cl_qlist_insert_list_head,
782 /****f* Component Library: Quick List/cl_qlist_insert_tail
787 *	The cl_qlist_insert_tail function inserts a list item at the tail
788 *	of a quick list.
800 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_insert_tail()
804 	 * The list item must not already be part of the list.  Note that this  in cl_qlist_insert_tail()
805 	 * assertion may fail if an uninitialized list item happens to have its  in cl_qlist_insert_tail()
806 	 * list pointer equal to the specified list.  The chances of this  in cl_qlist_insert_tail()
836 *	In debug builds, cl_qlist_insert_tail asserts that the specified list item
837 *	is not already in the list.
840 *	Quick List, cl_qlist_insert_head, cl_qlist_insert_list_head,
846 /****f* Component Library: Quick List/cl_qlist_insert_list_head
871 *	Inserts all list items in the source list to the head of the
872 *	destination list. The ordering of the list items is preserved.
874 *	The list pointed to by the p_src_list parameter is empty when
878 *	Quick List, cl_qlist_insert_list_tail, cl_qlist_insert_head,
884 /****f* Component Library: Quick List/cl_qlist_insert_list_tail
909 *	Inserts all list items in the source list to the tail of the
910 *	destination list. The ordering of the list items is preserved.
912 *	The list pointed to by the p_src_list parameter is empty when
916 *	Quick List, cl_qlist_insert_list_head, cl_qlist_insert_head,
922 /****f* Component Library: Quick List/cl_qlist_insert_array_head
927 *	The cl_qlist_insert_array_head function inserts an array of list items
928 *	at the head of a quick list.
943 *		[in] Pointer to the first list item in an array of cl_list_item_t
950 *		[in] Size of the items added to the list. This is the stride in the
957 *	Inserts all the list items in the array specified by the p_array parameter
958 *	to the head of the quick list specified by the p_list parameter,
959 *	preserving ordering of the list items.
966 *	Quick List, cl_qlist_insert_array_tail, cl_qlist_insert_head,
971 /****f* Component Library: Quick List/cl_qlist_insert_array_tail
976 *	The cl_qlist_insert_array_tail function inserts an array of list items
977 *	at the tail of a quick list.
992 *		[in] Pointer to the first list item in an array of cl_list_item_t
999 *		[in] Size of the items added to the list. This is the stride in the
1006 *	Inserts all the list items in the array specified by the p_array parameter
1007 *	to the tail of the quick list specified by the p_list parameter,
1008 *	preserving ordering of the list items.
1015 *	Quick List, cl_qlist_insert_array_head, cl_qlist_insert_head,
1020 /****f* Component Library: Quick List/cl_qlist_insert_prev
1025 *	The cl_qlist_insert_prev function inserts a list item before a
1026 *	specified list item in a quick list.
1041 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_insert_prev()
1045 	 * The list item must not already be part of the list.  Note that this  in cl_qlist_insert_prev()
1046 	 * assertion may fail if an uninitialized list item happens to have its  in cl_qlist_insert_prev()
1047 	 * list pointer equal to the specified list.  The chances of this  in cl_qlist_insert_prev()
1070 *		[in] Pointer to a cl_list_item_t structure to add to the quick list.
1076 *	Inserts the new list item before the list item specified by p_list_item.
1079 *	Quick List, cl_qlist_insert_next, cl_qlist_insert_head,
1084 /****f* Component Library: Quick List/cl_qlist_insert_next
1089 *	The cl_qlist_insert_next function inserts a list item after a specified
1090 *	list item in a quick list.
1105 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_insert_next()
1109 	 * The list item must not already be part of the list.  Note that this  in cl_qlist_insert_next()
1110 	 * assertion may fail if an uninitialized list item happens to have its  in cl_qlist_insert_next()
1111 	 * list pointer equal to the specified list.  The chances of this  in cl_qlist_insert_next()
1134 *		[in] Pointer to a cl_list_item_t structure to add to the quick list.
1140 *	Inserts the new list item after the list item specified by p_list_item.
1141 *	The list item specified by p_list_item must be in the quick list.
1144 *	Quick List, cl_qlist_insert_prev, cl_qlist_insert_head,
1149 /****f* Component Library: Quick List/cl_qlist_remove_head
1154 *	The cl_qlist_remove_head function removes and returns the list item
1155 *	at the head of a quick list.
1165 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_remove_head()
1169 	/* CL_ASSERT that the list item is part of the list. */  in cl_qlist_remove_head()
1176 	/* Clear the item's link to the list. */  in cl_qlist_remove_head()
1193 *	Returns a pointer to the list item formerly at the head of the quick list.
1195 *	Pointer to the list end if the list was empty.
1198 *	Quick List, cl_qlist_remove_tail, cl_qlist_remove_all, cl_qlist_remove_item,
1202 /****f* Component Library: Quick List/cl_qlist_remove_tail
1207 *	The cl_qlist_remove_tail function removes and returns the list item
1208 *	at the tail of a quick list.
1218 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_remove_tail()
1222 	/* CL_ASSERT that the list item is part of the list. */  in cl_qlist_remove_tail()
1229 	/* Clear the item's link to the list. */  in cl_qlist_remove_tail()
1246 *	Returns a pointer to the list item formerly at the tail of the quick list.
1248 *	Pointer to the list end if the list was empty.
1251 *	Quick List, cl_qlist_remove_head, cl_qlist_remove_all, cl_qlist_remove_item,
1255 /****f* Component Library: Quick List/cl_qlist_remove_item
1260 *	The cl_qlist_remove_item function removes a specific list item from a quick list.
1272 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_remove_item()
1274 	/* CL_ASSERT that the list item is part of the list. */  in cl_qlist_remove_item()
1281 	/* Clear the item's link to the list. */  in cl_qlist_remove_item()
1302 *	Removes the list item pointed to by the p_list_item parameter from
1303 *	its list.
1306 *	Quick List, cl_qlist_remove_head, cl_qlist_remove_tail, cl_qlist_remove_all,
1310 /****f* Component Library: Quick List/cl_qlist_remove_all
1315 *	The cl_qlist_remove_all function removes all items from a quick list.
1326 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_remove_all()
1347 *	Quick List, cl_qlist_remove_head, cl_qlist_remove_tail,
1351 /****f* Component Library: Quick List/cl_is_item_in_qlist
1357 *	list item in a quick list.
1373 *	TRUE if the list item was found in the quick list.
1378 *	Quick List, cl_qlist_remove_item, cl_list_item_t
1381 /****f* Component Library: Quick List/cl_qlist_find_next
1387 *	search for an item, starting from a given list item.
1410 *		callback function is provided, or value compared to the quick list's
1411 *		list items.
1414 *	Pointer to the list item, if found.
1419 *	cl_qlist_find_next does not remove list items from the list.
1420 *	The list item is returned when the function specified by the pfn_func
1421 *	parameter returns CL_SUCCESS.  The list item from which the search starts is
1424 *	The function provided by the pfn_func must not perform any list operations,
1425 *	as these would corrupt the list.
1428 *	Quick List, cl_qlist_find_prev, cl_qlist_find_from_head,
1433 /****f* Component Library: Quick List/cl_qlist_find_prev
1439 *	search backward for an item, starting from a given list item.
1462 *		callback function is provided, or value compared to the quick list's
1463 *		list items.
1466 *	Pointer to the list item, if found.
1471 *	cl_qlist_find_prev does not remove list items from the list.
1472 *	The list item is returned when the function specified by the pfn_func
1473 *	parameter returns CL_SUCCESS.  The list item from which the search starts is
1476 *	The function provided by the pfn_func must not perform any list operations,
1477 *	as these would corrupt the list.
1480 *	Quick List, cl_qlist_find_next, cl_qlist_find_from_head,
1485 /****f* Component Library: Quick List/cl_qlist_find_from_head
1491 *	search for an item, starting at the head of a quick list.
1504 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_find_from_head()
1525 *		callback function is provided, or value compared to the quick list's
1526 *		list items.
1529 *	Pointer to the list item, if found.
1531 *	Pointer to the list end otherwise
1534 *	cl_qlist_find_from_head does not remove list items from the list.
1535 *	The list item is returned when the function specified by the pfn_func
1538 *	The function provided by the pfn_func parameter must not perform any list
1539 *	operations, as these would corrupt the list.
1542 *	Quick List, cl_qlist_find_from_tail, cl_qlist_find_next, cl_qlist_find_prev,
1547 /****f* Component Library: Quick List/cl_qlist_find_from_tail
1553 *	search for an item, starting at the tail of a quick list.
1566 	/* CL_ASSERT that the list was initialized. */  in cl_qlist_find_from_tail()
1587 *		callback function is provided, or value compared to the quick list's
1588 *		list items.
1591 *	Pointer to the list item, if found.
1593 *	Pointer to the list end otherwise
1596 *	cl_qlist_find_from_tail does not remove list items from the list.
1597 *	The list item is returned when the function specified by the pfn_func
1600 *	The function provided by the pfn_func parameter must not perform any list
1601 *	operations, as these would corrupt the list.
1604 *	Quick List, cl_qlist_find_from_head, cl_qlist_find_next, cl_qlist_find_prev,
1609 /****f* Component Library: Quick List/cl_qlist_apply_func
1615 *	for every list item stored in a quick list.
1629 *		[in] Function invoked for every item in the quick list.
1640 *	The function provided must not perform any list operations, as these
1641 *	would corrupt the quick list.
1644 *	Quick List, cl_qlist_find_from_head, cl_qlist_find_from_tail,
1648 /****f* Component Library: Quick List/cl_qlist_move_items
1653 *	The cl_qlist_move_items function moves list items from one list to
1667 *		list items are removed.
1671 *		list items are added.
1686 *	the related list item is removed from p_src_list and inserted at the tail
1691 *	in a single list iteration.
1693 *	The function specified by pfn_func must not perform any list operations,
1694 *	as these would corrupt the list.
1697 *	Quick List, cl_qlist_find_from_head, cl_qlist_find_from_tail,