2 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
6 * This software is available to you under a choice of one of two
7 * licenses. You may choose to be licensed under the terms of the GNU
8 * General Public License (GPL) Version 2, available from the file
9 * COPYING in the main directory of this source tree, or the
10 * OpenIB.org BSD license below:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
20 * - Redistributions in binary form must reproduce the above
21 * copyright notice, this list of conditions and the following
22 * disclaimer in the documentation and/or other materials
23 * provided with the distribution.
25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
38 * Declaration of list.
44 #include <complib/cl_qlist.h>
45 #include <complib/cl_qpool.h>
48 # define BEGIN_C_DECLS extern "C" {
49 # define END_C_DECLS }
50 #else /* !__cplusplus */
51 # define BEGIN_C_DECLS
53 #endif /* __cplusplus */
56 /****h* Component Library/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
65 * fail, and callers should trap for such failures.
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
72 * treated as opaque and should be manipulated only through the provided
83 * cl_pfn_list_apply_t, cl_pfn_list_find_t
85 * Initialization/Destruction:
86 * cl_list_construct, cl_list_init, cl_list_destroy
89 * cl_list_next, cl_list_prev, cl_list_head, cl_list_tail,
93 * cl_list_insert_head, cl_list_insert_tail,
94 * cl_list_insert_array_head, cl_list_insert_array_tail,
95 * cl_list_insert_prev, cl_list_insert_next,
96 * cl_list_remove_head, cl_list_remove_tail,
97 * cl_list_remove_object, cl_list_remove_item, cl_list_remove_all
100 * cl_is_object_in_list, cl_list_find_from_head, cl_list_find_from_tail,
104 * cl_list_count, cl_is_list_empty, cl_is_list_inited
106 /****s* Component Library: List/cl_list_t
113 * The cl_list_t structure should be treated as opaque and should be
114 * manipulated only through the provided functions.
118 typedef struct _cl_list {
120 cl_qpool_t list_item_pool;
125 * Quick list of items stored in the list.
128 * Quick pool of list objects for storing objects in the quick list.
134 /****d* Component Library: List/cl_list_iterator_t
139 * Iterator type used to walk a list.
143 typedef const cl_list_item_t *cl_list_iterator_t;
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
155 * cl_pfn_list_apply_t
158 * The cl_pfn_list_apply_t function type defines the prototype for functions
159 * used to iterate objects in a list.
164 (*cl_pfn_list_apply_t) (IN void *const p_object, IN void *context);
168 * [in] Pointer to an object stored in a list.
171 * [in] Context provided in a call to cl_list_apply_func.
174 * This function does not return a value.
177 * This function type is provided as function prototype reference for the
178 * function provided by users as a parameter to the cl_list_apply_func
182 * List, cl_list_apply_func
185 /****d* Component Library: List/cl_pfn_list_find_t
190 * The cl_pfn_list_find_t function type defines the prototype for functions
191 * used to find objects in a list.
196 (*cl_pfn_list_find_t) (IN const void *const p_object, IN void *context);
200 * [in] Pointer to an object stored in a list.
203 * [in] Context provided in a call to ListFindFromHead or ListFindFromTail.
206 * Return CL_SUCCESS if the desired item was found. This stops list iteration.
208 * Return CL_NOT_FOUND to continue the list iteration.
211 * This function type is provided as function prototype reference for the
212 * function provided by users as a parameter to the cl_list_find_from_head
213 * and cl_list_find_from_tail functions.
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.
228 void cl_list_construct(IN cl_list_t * const p_list);
232 * [in] Pointer to cl_list_t object whose state to initialize.
235 * This function does not return a value.
238 * Allows calling cl_list_init, cl_list_destroy and cl_is_list_inited.
240 * Calling cl_list_construct is a prerequisite to calling any other
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
253 * initialized successfully.
257 static inline boolean_t cl_is_list_inited(IN const cl_list_t * const p_list)
259 /* CL_ASSERT that a non-null pointer is provided. */
262 * The pool is the last thing initialized. If it is initialized, the
263 * list is initialized too.
265 return (cl_is_qpool_inited(&p_list->list_item_pool));
271 * [in] Pointer to a cl_list_t structure whose initilization state
275 * TRUE if the list was initialized successfully.
280 * Allows checking the state of a list to determine if invoking
281 * member functions is appropriate.
287 /****f* Component Library: List/cl_list_init
292 * The cl_list_init function initializes a list for use.
297 cl_list_init(IN cl_list_t * const p_list, IN const size_t min_items);
301 * [in] Pointer to cl_list_t structure to initialize.
304 * [in] Minimum number of items that can be stored. All necessary
305 * allocations to allow storing the minimum number of items is performed
306 * at initialization time.
309 * CL_SUCCESS if the list was initialized successfully.
311 * CL_INSUFFICIENT_MEMORY if there was not enough memory for initialization.
314 * The list will always be able to store at least as many items as specified
315 * by the min_items parameter.
318 * List, cl_list_construct, cl_list_destroy, cl_list_insert_head,
319 * cl_list_insert_tail, cl_list_remove_head, cl_list_remove_tail
322 /****f* Component Library: List/cl_list_destroy
327 * The cl_list_destroy function destroys a list.
331 void cl_list_destroy(IN cl_list_t * const p_list);
335 * [in] Pointer to cl_list_t structure to destroy.
338 * This function does not return a value.
341 * cl_list_destroy does not affect any of the objects stored in the list,
342 * but does release all memory allocated internally. Further operations
343 * should not be attempted on the list after cl_list_destroy is invoked.
345 * This function should only be called after a call to cl_list_construct
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.
363 static inline boolean_t cl_is_list_empty(IN const cl_list_t * const p_list)
366 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
367 return (cl_is_qlist_empty(&p_list->list));
373 * [in] Pointer to a cl_list_t structure.
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
386 * cl_list_insert_head
389 * The cl_list_insert_head function inserts an object at the head of a list.
393 static inline cl_status_t
394 cl_list_insert_head(IN cl_list_t * const p_list, IN const void *const p_object)
396 cl_pool_obj_t *p_pool_obj;
399 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
401 /* Get a list item to add to the list. */
402 p_pool_obj = (cl_pool_obj_t *) cl_qpool_get(&p_list->list_item_pool);
404 return (CL_INSUFFICIENT_MEMORY);
406 p_pool_obj->p_object = p_object;
407 cl_qlist_insert_head(&p_list->list, &p_pool_obj->pool_item.list_item);
414 * [in] Pointer to a cl_list_t structure into which to insert the object.
417 * [in] Pointer to an object to insert into the list.
420 * CL_SUCCESS if the insertion was successful.
422 * CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.
425 * Inserts the specified object at the head of the list. List insertion
426 * operations are guaranteed to work for the minimum number of items as
427 * specified in cl_list_init by the min_items parameter.
430 * List, cl_list_insert_tail, cl_list_insert_array_head,
431 * cl_list_insert_array_tail, cl_list_insert_prev, cl_list_insert_next,
432 * cl_list_remove_head
435 /****f* Component Library: List/cl_list_insert_tail
437 * cl_list_insert_tail
440 * The cl_list_insert_tail function inserts an object at the tail of a list.
444 static inline cl_status_t
445 cl_list_insert_tail(IN cl_list_t * const p_list, IN const void *const p_object)
447 cl_pool_obj_t *p_pool_obj;
450 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
452 /* Get a list item to add to the list. */
453 p_pool_obj = (cl_pool_obj_t *) cl_qpool_get(&p_list->list_item_pool);
455 return (CL_INSUFFICIENT_MEMORY);
457 p_pool_obj->p_object = p_object;
458 cl_qlist_insert_tail(&p_list->list, &p_pool_obj->pool_item.list_item);
465 * [in] Pointer to a cl_list_t structure into which to insert the object.
468 * [in] Pointer to an object to insert into the list.
471 * CL_SUCCESS if the insertion was successful.
473 * CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.
476 * Inserts the specified object at the tail of the list. List insertion
477 * operations are guaranteed to work for the minimum number of items as
478 * specified in cl_list_init by the min_items parameter.
481 * List, cl_list_insert_head, cl_list_insert_array_head,
482 * cl_list_insert_array_tail, cl_list_insert_prev, cl_list_insert_next,
483 * cl_list_remove_tail
486 /****f* Component Library: List/cl_list_insert_array_head
488 * cl_list_insert_array_head
491 * The cl_list_insert_array_head function inserts an array of objects
492 * at the head of a list.
497 cl_list_insert_array_head(IN cl_list_t * const p_list,
498 IN const void *const p_array,
499 IN uint32_t item_count, IN const uint32_t item_size);
503 * [in] Pointer to a cl_list_t structure into which to insert the objects.
506 * [in] Pointer to the first object in an array.
509 * [in] Number of objects in the array.
512 * [in] Size of the objects added to the list. This is the stride in the
513 * array from one object to the next.
516 * CL_SUCCESS if the insertion was successful.
518 * CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.
521 * Inserts all objects in the array to the head of the list, preserving the
522 * ordering of the objects. If not successful, no items are added.
523 * List insertion operations are guaranteed to work for the minimum number
524 * of items as specified in cl_list_init by the min_items parameter.
527 * List, cl_list_insert_array_tail, cl_list_insert_head, cl_list_insert_tail,
528 * cl_list_insert_prev, cl_list_insert_next
531 /****f* Component Library: List/cl_list_insert_array_tail
533 * cl_list_insert_array_tail
536 * The cl_list_insert_array_tail function inserts an array of objects
537 * at the tail of a list.
542 cl_list_insert_array_tail(IN cl_list_t * const p_list,
543 IN const void *const p_array,
544 IN uint32_t item_count, IN const uint32_t item_size);
548 * [in] Pointer to a cl_list_t structure into which to insert the objects.
551 * [in] Pointer to the first object in an array.
554 * [in] Number of objects in the array.
557 * [in] Size of the objects added to the list. This is the stride in the
558 * array from one object to the next.
561 * CL_SUCCESS if the insertion was successful.
563 * CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.
566 * Inserts all objects in the array to the tail of the list, preserving the
567 * ordering of the objects. If not successful, no items are added.
568 * List insertion operations are guaranteed to work for the minimum number
569 * of items as specified in cl_list_init by the min_items parameter.
572 * List, cl_list_insert_array_head, cl_list_insert_head, cl_list_insert_tail,
573 * cl_list_insert_prev, cl_list_insert_next
576 /****f* Component Library: List/cl_list_insert_next
578 * cl_list_insert_next
581 * The cl_list_insert_next function inserts an object in a list after
582 * the object associated with a given iterator.
586 static inline cl_status_t
587 cl_list_insert_next(IN cl_list_t * const p_list,
588 IN cl_list_iterator_t iterator,
589 IN const void *const p_object)
591 cl_pool_obj_t *p_pool_obj;
594 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
596 /* Get a list item to add to the list. */
597 p_pool_obj = (cl_pool_obj_t *) cl_qpool_get(&p_list->list_item_pool);
599 return (CL_INSUFFICIENT_MEMORY);
601 p_pool_obj->p_object = p_object;
602 cl_qlist_insert_next(&p_list->list, (cl_list_item_t *) iterator,
603 &p_pool_obj->pool_item.list_item);
610 * [in] Pointer to a cl_list_t structure into which to insert the object.
613 * [in] cl_list_iterator_t returned by a previous call to cl_list_head,
614 * cl_list_tail, cl_list_next, or cl_list_prev.
617 * [in] Pointer to an object to insert into the list.
620 * CL_SUCCESS if the insertion was successful.
622 * CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.
625 * List, cl_list_insert_prev, cl_list_insert_head, cl_list_insert_tail,
626 * cl_list_insert_array_head, cl_list_insert_array_tail
629 /****f* Component Library: List/cl_list_insert_prev
631 * cl_list_insert_prev
634 * The cl_list_insert_prev function inserts an object in a list before
635 * the object associated with a given iterator.
639 static inline cl_status_t
640 cl_list_insert_prev(IN cl_list_t * const p_list,
641 IN cl_list_iterator_t iterator,
642 IN const void *const p_object)
644 cl_pool_obj_t *p_pool_obj;
647 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
649 /* Get a list item to add to the list. */
650 p_pool_obj = (cl_pool_obj_t *) cl_qpool_get(&p_list->list_item_pool);
652 return (CL_INSUFFICIENT_MEMORY);
654 p_pool_obj->p_object = p_object;
655 cl_qlist_insert_prev(&p_list->list, (cl_list_item_t *) iterator,
656 &p_pool_obj->pool_item.list_item);
663 * [in] Pointer to a cl_list_t structure into which to insert the object.
666 * [in] cl_list_iterator_t returned by a previous call to cl_list_head,
667 * cl_list_tail, cl_list_next, or cl_list_prev.
670 * [in] Pointer to an object to insert into the list.
673 * CL_SUCCESS if the insertion was successful.
675 * CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.
678 * List, cl_list_insert_next, cl_list_insert_head, cl_list_insert_tail,
679 * cl_list_insert_array_head, cl_list_insert_array_tail
682 /****f* Component Library: List/cl_list_remove_head
684 * cl_list_remove_head
687 * The cl_list_remove_head function removes an object from the head of a list.
691 static inline void *cl_list_remove_head(IN cl_list_t * const p_list)
693 cl_pool_obj_t *p_pool_obj;
697 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
699 /* See if the list is empty. */
700 if (cl_is_qlist_empty(&p_list->list))
703 /* Get the item at the head of the list. */
704 p_pool_obj = (cl_pool_obj_t *) cl_qlist_remove_head(&p_list->list);
706 p_obj = (void *)p_pool_obj->p_object;
707 /* Place the pool item back into the pool. */
708 cl_qpool_put(&p_list->list_item_pool, &p_pool_obj->pool_item);
716 * [in] Pointer to a cl_list_t structure from which to remove an object.
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,
725 * cl_list_remove_item, cl_list_insert_head
728 /****f* Component Library: List/cl_list_remove_tail
730 * cl_list_remove_tail
733 * The cl_list_remove_tail function removes an object from the tail of a list.
737 static inline void *cl_list_remove_tail(IN cl_list_t * const p_list)
739 cl_pool_obj_t *p_pool_obj;
742 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
744 /* See if the list is empty. */
745 if (cl_is_qlist_empty(&p_list->list))
748 /* Get the item at the head of the list. */
749 p_pool_obj = (cl_pool_obj_t *) cl_qlist_remove_tail(&p_list->list);
751 /* Place the list item back into the pool. */
752 cl_qpool_put(&p_list->list_item_pool, &p_pool_obj->pool_item);
754 return ((void *)p_pool_obj->p_object);
760 * [in] Pointer to a cl_list_t structure from which to remove an object.
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,
769 * cl_list_remove_item, cl_list_insert_head
772 /****f* Component Library: List/cl_list_remove_all
777 * The cl_list_remove_all function removes all objects from a list,
782 static inline void cl_list_remove_all(IN cl_list_t * const p_list)
785 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
787 /* Return all the list items to the pool. */
788 cl_qpool_put_list(&p_list->list_item_pool, &p_list->list);
794 * [in] Pointer to a cl_list_t structure from which to remove all objects.
797 * This function does not return a value.
800 * List, cl_list_remove_head, cl_list_remove_tail, cl_list_remove_object,
801 * cl_list_remove_item
804 /****f* Component Library: List/cl_list_remove_object
806 * cl_list_remove_object
809 * The cl_list_remove_object function removes a specific object from a list.
814 cl_list_remove_object(IN cl_list_t * const p_list,
815 IN const void *const p_object);
819 * [in] Pointer to a cl_list_t structure from which to remove the object.
822 * [in] Pointer to an object to remove from the list.
825 * CL_SUCCESS if the object was removed.
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
839 * cl_list_remove_item
842 * The cl_list_remove_item function removes an object from the head of a list.
847 cl_list_remove_item(IN cl_list_t * const p_list, IN cl_list_iterator_t iterator)
850 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
852 cl_qlist_remove_item(&p_list->list, (cl_list_item_t *) iterator);
854 /* Place the list item back into the pool. */
855 cl_qpool_put(&p_list->list_item_pool, (cl_pool_item_t *) iterator);
861 * [in] Pointer to a cl_list_t structure from which to remove the item.
864 * [in] cl_list_iterator_t returned by a previous call to cl_list_head,
865 * cl_list_tail, cl_list_next, or cl_list_prev.
868 * This function does not return a value.
871 * List, cl_list_remove_object, cl_list_remove_head, cl_list_remove_tail,
875 /****f* Component Library: List/cl_is_object_in_list
877 * cl_is_object_in_list
880 * The cl_is_object_in_list function returns whether an object
881 * is stored in a list.
886 cl_is_object_in_list(IN const cl_list_t * const p_list,
887 IN const void *const p_object);
891 * [in] Pointer to a cl_list_t structure in which to look for the object.
894 * [in] Pointer to an object stored in a list.
897 * TRUE if p_object was found in the list.
905 /****f* Component Library: List/cl_list_end
910 * The cl_list_end function returns returns the list iterator for
915 static inline cl_list_iterator_t cl_list_end(IN const cl_list_t * const p_list)
918 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
920 return (cl_qlist_end(&p_list->list));
926 * [in] Pointer to a cl_list_t structure for which the iterator for the
927 * object at the head is to be returned.
930 * cl_list_iterator_t for the end of the list.
933 * Use cl_list_obj to retrieve the object associated with the
934 * returned cl_list_iterator_t.
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.
951 static inline cl_list_iterator_t cl_list_head(IN const cl_list_t * const p_list)
954 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
956 return (cl_qlist_head(&p_list->list));
962 * [in] Pointer to a cl_list_t structure for which the iterator for the
963 * object at the head is to be returned.
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.
971 * Use cl_list_obj to retrieve the object associated with the
972 * returned cl_list_iterator_t.
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.
989 static inline cl_list_iterator_t cl_list_tail(IN const cl_list_t * const p_list)
992 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
994 return (cl_qlist_tail(&p_list->list));
1000 * [in] Pointer to a cl_list_t structure for which the iterator for the
1001 * object at the tail is to be returned.
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.
1009 * Use cl_list_obj to retrieve the object associated with the
1011 * returned cl_list_iterator_t.
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.
1028 static inline cl_list_iterator_t cl_list_next(IN cl_list_iterator_t iterator)
1030 CL_ASSERT(iterator);
1032 return (cl_qlist_next(iterator));
1038 * [in] Pointer to a cl_list_t structure for which the iterator for the
1039 * next object is to be returned.
1042 * [in] cl_list_iterator_t returned by a previous call to cl_list_head,
1043 * cl_list_tail, cl_list_next, or cl_list_prev.
1046 * cl_list_iterator_t for the object following the object associated with
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.
1052 * Use cl_list_obj to retrieve the object associated with the
1053 * returned cl_list_iterator_t.
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.
1070 static inline cl_list_iterator_t cl_list_prev(IN cl_list_iterator_t iterator)
1072 CL_ASSERT(iterator);
1074 return (cl_qlist_prev(iterator));
1080 * [in] Pointer to a cl_list_t structure for which the iterator for the
1081 * next object is to be returned.
1084 * [in] cl_list_iterator_t returned by a previous call to cl_list_head,
1085 * cl_list_tail, cl_list_next, or cl_list_prev.
1088 * cl_list_iterator_t for the object preceding the object associated with
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.
1094 * Use cl_list_obj to retrieve the object associated with the
1095 * returned cl_list_iterator_t.
1098 * List, cl_list_next, cl_list_head, cl_list_tail, cl_list_end,
1102 /****f* Component Library: List/cl_list_obj
1107 * The cl_list_obj function returns the object associated
1108 * with a list iterator.
1112 static inline void *cl_list_obj(IN cl_list_iterator_t iterator)
1114 CL_ASSERT(iterator);
1116 return ((void *)((cl_pool_obj_t *) iterator)->p_object);
1122 * [in] cl_list_iterator_t returned by a previous call to cl_list_head,
1123 * cl_list_tail, cl_list_next, or cl_list_prev whose object is requested.
1126 * Pointer to the object associated with the list iterator specified
1127 * by the iterator parameter.
1130 * List, cl_list_head, cl_list_tail, cl_list_next, cl_list_prev
1133 /****f* Component Library: List/cl_list_find_from_head
1135 * cl_list_find_from_head
1138 * The cl_list_find_from_head function uses a specified function
1139 * to search for an object starting from the head of a list.
1144 cl_list_find_from_head(IN const cl_list_t * const p_list,
1145 IN cl_pfn_list_find_t pfn_func,
1146 IN const void *const context);
1150 * [in] Pointer to a cl_list_t structure to search.
1153 * [in] Function invoked to determine if a match was found.
1154 * See the cl_pfn_list_find_t function type declaration for details
1155 * about the callback function.
1158 * [in] Value to pass to the callback functions to provide context.
1161 * Returns the iterator for the object if found.
1163 * Returns the iterator for the list end otherwise.
1166 * cl_list_find_from_head does not remove the found object from
1167 * the list. The iterator for the object is returned when the function
1168 * provided by the pfn_func parameter returns CL_SUCCESS. 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,
1174 * cl_pfn_list_find_t
1177 /****f* Component Library: List/cl_list_find_from_tail
1179 * cl_list_find_from_tail
1182 * The cl_list_find_from_tail function uses a specified function
1183 * to search for an object starting from the tail of a list.
1188 cl_list_find_from_tail(IN const cl_list_t * const p_list,
1189 IN cl_pfn_list_find_t pfn_func,
1190 IN const void *const context);
1194 * [in] Pointer to a cl_list_t structure to search.
1197 * [in] Function invoked to determine if a match was found.
1198 * See the cl_pfn_list_find_t function type declaration for details
1199 * about the callback function.
1202 * [in] Value to pass to the callback functions to provide context.
1205 * Returns the iterator for the object if found.
1207 * Returns the iterator for the list end otherwise.
1210 * cl_list_find_from_tail does not remove the found object from
1211 * the list. The iterator for the object is returned when the function
1212 * provided by the pfn_func parameter returns CL_SUCCESS. 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,
1218 * cl_pfn_list_find_t
1221 /****f* Component Library: List/cl_list_apply_func
1223 * cl_list_apply_func
1226 * The cl_list_apply_func function executes a specified function for every
1227 * object stored in a list.
1232 cl_list_apply_func(IN const cl_list_t * const p_list,
1233 IN cl_pfn_list_apply_t pfn_func,
1234 IN const void *const context);
1238 * [in] Pointer to a cl_list_t structure to iterate.
1241 * [in] Function invoked for every item in a list.
1242 * See the cl_pfn_list_apply_t function type declaration for details
1243 * about the callback function.
1246 * [in] Value to pass to the callback functions to provide context.
1249 * This function does not return a value.
1252 * cl_list_apply_func invokes the specified callback function for every
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,
1259 * cl_pfn_list_apply_t
1262 /****f* Component Library: List/cl_list_count
1267 * The cl_list_count function returns the number of objects stored in a list.
1271 static inline size_t cl_list_count(IN const cl_list_t * const p_list)
1274 CL_ASSERT(cl_is_qpool_inited(&p_list->list_item_pool));
1276 return (cl_qlist_count(&p_list->list));
1282 * [in] Pointer to a cl_list_t structure whose object to count.
1285 * Number of objects stored in the specified list.
1292 #endif /* _CL_LIST_H_ */