17  *        copyright notice, this list of conditions and the following
21  *        copyright notice, this list of conditions and the following
38  *	Declaration of list.
56 /****h* Component Library/List
58 *	List
61 *	List stores objects in a doubly linked list.
63 *	Unlike quick list, users pass pointers to the object being stored, rather
64 *	than to a cl_list_item_t structure.  Insertion operations on a list can
67 *	Use quick list in situations where insertion failures cannot be tolerated.
69 *	List is not thread safe, and users must provide serialization.
71 *	The list functions operates on a cl_list_t structure which should be
106 /****s* Component Library: List/cl_list_t
111 *	List structure.
119 	cl_qlist_t list;  member
124 *	list
125 *		Quick list of items stored in the list.
128 *		Quick pool of list objects for storing objects in the quick list.
131 *	List
134 /****d* Component Library: List/cl_list_iterator_t
139 *	Iterator type used to walk a list.
146 *	The iterator should be treated as opaque to prevent corrupting the list.
149 *	List, cl_list_head, cl_list_tail, cl_list_next, cl_list_prev,
153 /****d* Component Library: List/cl_pfn_list_apply_t
159 *	used to iterate objects in a list.
168 *		[in] Pointer to an object stored in a list.
182 *	List, cl_list_apply_func
185 /****d* Component Library: List/cl_pfn_list_find_t
191 *	used to find objects in a list.
200 *		[in] Pointer to an object stored in a list.
206 *	Return CL_SUCCESS if the desired item was found.  This stops list iteration.
208 *	Return CL_NOT_FOUND to continue the list iteration.
216 *	List, cl_list_find_from_head, cl_list_find_from_tail
219 /****f* Component Library: List/cl_list_construct
224 *	The cl_list_construct function constructs a list.
241 *	list function except cl_list_init.
244 *	List, cl_list_init, cl_list_destroy, cl_is_list_inited
247 /****f* Component Library: List/cl_is_list_inited
252 *	The cl_is_list_inited function returns whether a list was
263 	 * list is initialized too.  in cl_is_list_inited()
275 *	TRUE if the list was initialized successfully.
280 *	Allows checking the state of a list to determine if invoking
284 *	List
287 /****f* Component Library: List/cl_list_init
292 *	The cl_list_init function initializes a list for use.
309 *	CL_SUCCESS if the list was initialized successfully.
314 *	The list will always be able to store at least as many items as specified
318 *	List, cl_list_construct, cl_list_destroy, cl_list_insert_head,
322 /****f* Component Library: List/cl_list_destroy
327 *	The cl_list_destroy function destroys a list.
341 *	cl_list_destroy does not affect any of the objects stored in the list,
343 *	should not be attempted on the list after cl_list_destroy is invoked.
348 *	In debug builds, cl_list_destroy asserts if the list is not empty.
351 *	List, cl_list_construct, cl_list_init
354 /****f* Component Library: List/cl_is_list_empty
359 *	The cl_is_list_empty function returns whether a list is empty.
367 	return (cl_is_qlist_empty(&p_list->list));  in cl_is_list_empty()
376 *	TRUE if the specified list is empty.
381 *	List, cl_list_count, cl_list_remove_all
384 /****f* Component Library: List/cl_list_insert_head
389 *	The cl_list_insert_head function inserts an object at the head of a list.
401 	/* Get a list item to add to the list. */  in cl_list_insert_head()
407 	cl_qlist_insert_head(&p_list->list, &p_pool_obj->pool_item.list_item);  in cl_list_insert_head()
417 *		[in] Pointer to an object to insert into the list.
425 *	Inserts the specified object at the head of the list.  List insertion
430 *	List, cl_list_insert_tail, cl_list_insert_array_head,
435 /****f* Component Library: List/cl_list_insert_tail
440 *	The cl_list_insert_tail function inserts an object at the tail of a list.
452 	/* Get a list item to add to the list. */  in cl_list_insert_tail()
458 	cl_qlist_insert_tail(&p_list->list, &p_pool_obj->pool_item.list_item);  in cl_list_insert_tail()
468 *		[in] Pointer to an object to insert into the list.
476 *	Inserts the specified object at the tail of the list.  List insertion
481 *	List, cl_list_insert_head, cl_list_insert_array_head,
486 /****f* Component Library: List/cl_list_insert_array_head
492 *	at the head of a list.
512 *		[in] Size of the objects added to the list.  This is the stride in the
521 *	Inserts all objects in the array to the head of the list, preserving the
523 *	List insertion operations are guaranteed to work for the minimum number
527 *	List, cl_list_insert_array_tail, cl_list_insert_head, cl_list_insert_tail,
531 /****f* Component Library: List/cl_list_insert_array_tail
537 *	at the tail of a list.
557 *		[in] Size of the objects added to the list.  This is the stride in the
566 *	Inserts all objects in the array to the tail of the list, preserving the
568 *	List insertion operations are guaranteed to work for the minimum number
572 *	List, cl_list_insert_array_head, cl_list_insert_head, cl_list_insert_tail,
576 /****f* Component Library: List/cl_list_insert_next
581 *	The cl_list_insert_next function inserts an object in a list after
596 	/* Get a list item to add to the list. */  in cl_list_insert_next()
602 	cl_qlist_insert_next(&p_list->list, (cl_list_item_t *) iterator,  in cl_list_insert_next()
617 *		[in] Pointer to an object to insert into the list.
625 *	List, cl_list_insert_prev, cl_list_insert_head, cl_list_insert_tail,
629 /****f* Component Library: List/cl_list_insert_prev
634 *	The cl_list_insert_prev function inserts an object in a list before
649 	/* Get a list item to add to the list. */  in cl_list_insert_prev()
655 	cl_qlist_insert_prev(&p_list->list, (cl_list_item_t *) iterator,  in cl_list_insert_prev()
670 *		[in] Pointer to an object to insert into the list.
678 *	List, cl_list_insert_next, cl_list_insert_head, cl_list_insert_tail,
682 /****f* Component Library: List/cl_list_remove_head
687 *	The cl_list_remove_head function removes an object from the head of a list.
699 	/* See if the list is empty. */  in cl_list_remove_head()
700 	if (cl_is_qlist_empty(&p_list->list))  in cl_list_remove_head()
703 	/* Get the item at the head of the list. */  in cl_list_remove_head()
704 	p_pool_obj = (cl_pool_obj_t *) cl_qlist_remove_head(&p_list->list);  in cl_list_remove_head()
719 *	Returns the pointer to the object formerly at the head of the list.
721 *	NULL if the list was empty.
724 *	List, cl_list_remove_tail, cl_list_remove_all, cl_list_remove_object,
728 /****f* Component Library: List/cl_list_remove_tail
733 *	The cl_list_remove_tail function removes an object from the tail of a list.
744 	/* See if the list is empty. */  in cl_list_remove_tail()
745 	if (cl_is_qlist_empty(&p_list->list))  in cl_list_remove_tail()
748 	/* Get the item at the head of the list. */  in cl_list_remove_tail()
749 	p_pool_obj = (cl_pool_obj_t *) cl_qlist_remove_tail(&p_list->list);  in cl_list_remove_tail()
751 	/* Place the list item back into the pool. */  in cl_list_remove_tail()
763 *	Returns the pointer to the object formerly at the tail of the list.
765 *	NULL if the list was empty.
768 *	List, cl_list_remove_head, cl_list_remove_all, cl_list_remove_object,
772 /****f* Component Library: List/cl_list_remove_all
777 *	The cl_list_remove_all function removes all objects from a list,
787 	/* Return all the list items to the pool. */  in cl_list_remove_all()
788 	cl_qpool_put_list(&p_list->list_item_pool, &p_list->list);  in cl_list_remove_all()
800 *	List, cl_list_remove_head, cl_list_remove_tail, cl_list_remove_object,
804 /****f* Component Library: List/cl_list_remove_object
809 *	The cl_list_remove_object function removes a specific object from a list.
822 *		[in] Pointer to an object to remove from the list.
827 *	CL_NOT_FOUND if the object was not found in the list.
830 *	Removes the first occurrence of an object from a list.
833 *	List, cl_list_remove_item, cl_list_remove_head, cl_list_remove_tail,
837 /****f* Component Library: List/cl_list_remove_item
842 *	The cl_list_remove_item function removes an object from the head of a list.
852 	cl_qlist_remove_item(&p_list->list, (cl_list_item_t *) iterator);  in cl_list_remove_item()
854 	/* Place the list item back into the pool. */  in cl_list_remove_item()
871 *	List, cl_list_remove_object, cl_list_remove_head, cl_list_remove_tail,
875 /****f* Component Library: List/cl_is_object_in_list
881 *	is stored in a list.
894 *		[in] Pointer to an object stored in a list.
897 *	TRUE if p_object was found in the list.
902 *	List
905 /****f* Component Library: List/cl_list_end
910 *	The cl_list_end function returns returns the list iterator for
911 *	the end of a list.
920 	return (cl_qlist_end(&p_list->list));  in cl_list_end()
930 *	cl_list_iterator_t for the end of the list.
937 *	List, cl_list_head, cl_list_tail, cl_list_next, cl_list_prev,
941 /****f* Component Library: List/cl_list_head
946 *	The cl_list_head function returns returns a list iterator for
947 *	the head of a list.
956 	return (cl_qlist_head(&p_list->list));  in cl_list_head()
966 *	cl_list_iterator_t for the head of the list.
968 *	cl_list_iterator_t for the end of the list if the list is empty.
975 *	List, cl_list_tail, cl_list_next, cl_list_prev, cl_list_end,
979 /****f* Component Library: List/cl_list_tail
984 *	The cl_list_tail function returns returns a list iterator for
985 *	the tail of a list.
994 	return (cl_qlist_tail(&p_list->list));  in cl_list_tail()
1004 *	cl_list_iterator_t for the tail of the list.
1006 *	cl_list_iterator_t for the end of the list if the list is empty.
1014 *	List, cl_list_head, cl_list_next, cl_list_prev, cl_list_end,
1018 /****f* Component Library: List/cl_list_next
1023 *	The cl_list_next function returns a list iterator for the object stored
1024 *	in a list after the object associated with a given list iterator.
1047 *	the list iterator specified by the iterator parameter.
1049 *	cl_list_iterator_t for the end of the list if the list is empty.
1056 *	List, cl_list_prev, cl_list_head, cl_list_tail, cl_list_end,
1060 /****f* Component Library: List/cl_list_prev
1065 *	The cl_list_prev function returns a list iterator for the object stored
1066 *	in a list before the object associated with a given list iterator.
1089 *	the list iterator specified by the iterator parameter.
1091 *	cl_list_iterator_t for the end of the list if the list is empty.
1098 *	List, cl_list_next, cl_list_head, cl_list_tail, cl_list_end,
1102 /****f* Component Library: List/cl_list_obj
1108 *	with a list iterator.
1126 *	Pointer to the object associated with the list iterator specified
1130 *	List, cl_list_head, cl_list_tail, cl_list_next, cl_list_prev
1133 /****f* Component Library: List/cl_list_find_from_head
1139 *	to search for an object starting from the head of a list.
1163 *	Returns the iterator for the list end otherwise.
1167 *	the list.  The iterator for the object is returned when the function
1169 *	specified by the pfn_func parameter must not perform any list
1170 *	operations as these would corrupt the list.
1173 *	List, cl_list_find_from_tail, cl_list_apply_func_t,
1177 /****f* Component Library: List/cl_list_find_from_tail
1183 *	to search for an object starting from the tail of a list.
1207 *	Returns the iterator for the list end otherwise.
1211 *	the list.  The iterator for the object is returned when the function
1213 *	specified by the pfn_func parameter must not perform any list
1214 *	operations as these would corrupt the list.
1217 *	List, cl_list_find_from_head, cl_list_apply_func_t,
1221 /****f* Component Library: List/cl_list_apply_func
1227 *	object stored in a list.
1241 *		[in] Function invoked for every item in a list.
1253 *	object stored in the list, starting from the head.  The function specified
1254 *	by the pfn_func parameter must not perform any list operations as these
1255 *	would corrupt the list.
1258 *	List, cl_list_find_from_head, cl_list_find_from_tail,
1262 /****f* Component Library: List/cl_list_count
1267 *	The cl_list_count function returns the number of objects stored in a list.
1276 	return (cl_qlist_count(&p_list->list));  in cl_list_count()
1285 *	Number of objects stored in the specified list.
1288 *	List