[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_list.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      Declaration of list.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_LIST_H_\r
44 #define _CL_LIST_H_\r
45 \r
46 \r
47 #include <complib/cl_qlist.h>\r
48 #include <complib/cl_qpool.h>\r
49 \r
50 \r
51 /****h* Component Library/List\r
52 * NAME\r
53 *       List\r
54 *\r
55 * DESCRIPTION\r
56 *       List stores objects in a doubly linked list.\r
57 *\r
58 *       Unlike quick list, users pass pointers to the object being stored, rather\r
59 *       than to a cl_list_item_t structure.  Insertion operations on a list can\r
60 *       fail, and callers should trap for such failures.\r
61 *\r
62 *       Use quick list in situations where insertion failures cannot be tolerated.\r
63 *\r
64 *       List is not thread safe, and users must provide serialization.\r
65 *\r
66 *       The list functions operates on a cl_list_t structure which should be\r
67 *       treated as opaque and should be manipulated only through the provided\r
68 *       functions.\r
69 *\r
70 * SEE ALSO\r
71 *       Types:\r
72 *               cl_list_iterator_t\r
73 *\r
74 *       Structures:\r
75 *               cl_list_t\r
76 *\r
77 *       Callbacks:\r
78 *               cl_pfn_list_apply_t, cl_pfn_list_find_t\r
79 *\r
80 *       Initialization/Destruction:\r
81 *               cl_list_construct, cl_list_init, cl_list_destroy\r
82 *\r
83 *       Iteration:\r
84 *               cl_list_next, cl_list_prev, cl_list_head, cl_list_tail,\r
85 *               cl_list_end\r
86 *\r
87 *       Manipulation:\r
88 *               cl_list_insert_head, cl_list_insert_tail,\r
89 *               cl_list_insert_array_head, cl_list_insert_array_tail,\r
90 *               cl_list_insert_prev, cl_list_insert_next,\r
91 *               cl_list_remove_head, cl_list_remove_tail,\r
92 *               cl_list_remove_object, cl_list_remove_item, cl_list_remove_all\r
93 *\r
94 *       Search:\r
95 *               cl_is_object_in_list, cl_list_find_from_head, cl_list_find_from_tail,\r
96 *               cl_list_apply_func\r
97 *\r
98 *       Attributes:\r
99 *               cl_list_count, cl_is_list_empty, cl_is_list_inited\r
100 *********/\r
101 \r
102 \r
103 /****s* Component Library: List/cl_list_t\r
104 * NAME\r
105 *       cl_list_t\r
106 *\r
107 * DESCRIPTION\r
108 *       List structure.\r
109 *\r
110 *       The cl_list_t structure should be treated as opaque and should be\r
111 *       manipulated only through the provided functions.\r
112 *\r
113 * SYNOPSIS\r
114 */\r
115 typedef struct _cl_list\r
116 {\r
117         cl_qlist_t                      list;\r
118         cl_qpool_t                      list_item_pool;\r
119 \r
120 } cl_list_t;\r
121 /*\r
122 * FIELDS\r
123 *       list\r
124 *               Quick list of items stored in the list.\r
125 *\r
126 *       list_item_pool\r
127 *               Quick pool of list objects for storing objects in the quick list.\r
128 *\r
129 * SEE ALSO\r
130 *       List\r
131 *********/\r
132 \r
133 \r
134 /****d* Component Library: List/cl_list_iterator_t\r
135 * NAME\r
136 *       cl_list_iterator_t\r
137 *\r
138 * DESCRIPTION\r
139 *       Iterator type used to walk a list.\r
140 *\r
141 * SYNOPSIS\r
142 */\r
143 typedef const cl_list_item_t *cl_list_iterator_t;\r
144 /*\r
145 * NOTES\r
146 *       The iterator should be treated as opaque to prevent corrupting the list.\r
147 *\r
148 * SEE ALSO\r
149 *       List, cl_list_head, cl_list_tail, cl_list_next, cl_list_prev,\r
150 *       cl_list_obj\r
151 *********/\r
152 \r
153 \r
154 /****d* Component Library: List/cl_pfn_list_apply_t\r
155 * NAME\r
156 *       cl_pfn_list_apply_t\r
157 *\r
158 * DESCRIPTION\r
159 *       The cl_pfn_list_apply_t function type defines the prototype for functions\r
160 *       used to iterate objects in a list.\r
161 *\r
162 * SYNOPSIS\r
163 */\r
164 typedef void\r
165 (CL_API *cl_pfn_list_apply_t)(\r
166         IN      void* const                     p_object,\r
167         IN      void*                           context );\r
168 /*\r
169 * PARAMETERS\r
170 *       p_object\r
171 *               [in] Pointer to an object stored in a list.\r
172 *\r
173 *       context\r
174 *               [in] Context provided in a call to cl_list_apply_func.\r
175 *\r
176 * RETURN VALUE\r
177 *       This function does not return a value.\r
178 *\r
179 * NOTES\r
180 *       This function type is provided as function prototype reference for the\r
181 *       function provided by users as a parameter to the cl_list_apply_func\r
182 *       function.\r
183 *\r
184 * SEE ALSO\r
185 *       List, cl_list_apply_func\r
186 *********/\r
187 \r
188 \r
189 /****d* Component Library: List/cl_pfn_list_find_t\r
190 * NAME\r
191 *       cl_pfn_list_find_t\r
192 *\r
193 * DESCRIPTION\r
194 *       The cl_pfn_list_find_t function type defines the prototype for functions\r
195 *       used to find objects in a list.\r
196 *\r
197 * SYNOPSIS\r
198 */\r
199 typedef cl_status_t\r
200 (CL_API *cl_pfn_list_find_t)(\r
201         IN      const void* const       p_object,\r
202         IN      void*                           context );\r
203 /*\r
204 * PARAMETERS\r
205 *       p_object\r
206 *               [in] Pointer to an object stored in a list.\r
207 *\r
208 *       context\r
209 *               [in] Context provided in a call to ListFindFromHead or ListFindFromTail.\r
210 *\r
211 * RETURN VALUES\r
212 *       Return CL_SUCCESS if the desired item was found.  This stops list iteration.\r
213 *\r
214 *       Return CL_NOT_FOUND to continue the list iteration.\r
215 *\r
216 * NOTES\r
217 *       This function type is provided as function prototype reference for the\r
218 *       function provided by users as a parameter to the cl_list_find_from_head\r
219 *       and cl_list_find_from_tail functions.\r
220 *\r
221 * SEE ALSO\r
222 *       List, cl_list_find_from_head, cl_list_find_from_tail\r
223 *********/\r
224 \r
225 \r
226 #ifdef __cplusplus\r
227 extern "C"\r
228 {\r
229 #endif\r
230 \r
231 \r
232 /****f* Component Library: List/cl_list_construct\r
233 * NAME\r
234 *       cl_list_construct\r
235 *\r
236 * DESCRIPTION\r
237 *       The cl_list_construct function constructs a list.\r
238 *\r
239 * SYNOPSIS\r
240 */\r
241 CL_EXPORT void CL_API\r
242 cl_list_construct(\r
243         IN      cl_list_t* const        p_list );\r
244 /*\r
245 * PARAMETERS\r
246 *       p_list\r
247 *               [in] Pointer to cl_list_t object whose state to initialize.\r
248 *\r
249 * RETURN VALUE\r
250 *       This function does not return a value.\r
251 *\r
252 * NOTES\r
253 *       Allows calling cl_list_init, cl_list_destroy and cl_is_list_inited.\r
254 *\r
255 *       Calling cl_list_construct is a prerequisite to calling any other\r
256 *       list function except cl_list_init.\r
257 *\r
258 * SEE ALSO\r
259 *       List, cl_list_init, cl_list_destroy, cl_is_list_inited\r
260 *********/\r
261 \r
262 \r
263 /****f* Component Library: List/cl_is_list_inited\r
264 * NAME\r
265 *       cl_is_list_inited\r
266 *\r
267 * DESCRIPTION\r
268 *       The cl_is_list_inited function returns whether a list was\r
269 *       initialized successfully.\r
270 *\r
271 * SYNOPSIS\r
272 */\r
273 CL_INLINE boolean_t CL_API\r
274 cl_is_list_inited(\r
275         IN      const cl_list_t* const  p_list )\r
276 {\r
277         /* CL_ASSERT that a non-null pointer is provided. */\r
278         CL_ASSERT( p_list );\r
279         /*\r
280          * The pool is the last thing initialized.  If it is initialized, the\r
281          * list is initialized too.\r
282          */\r
283         return( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
284 }\r
285 /*\r
286 * PARAMETERS\r
287 *       p_list\r
288 *               [in] Pointer to a cl_list_t structure whose initilization state\r
289 *               to check.\r
290 *\r
291 * RETURN VALUES\r
292 *       TRUE if the list was initialized successfully.\r
293 *\r
294 *       FALSE otherwise.\r
295 *\r
296 * NOTES\r
297 *       Allows checking the state of a list to determine if invoking\r
298 *       member functions is appropriate.\r
299 *\r
300 * SEE ALSO\r
301 *       List\r
302 *********/\r
303 \r
304 \r
305 /****f* Component Library: List/cl_list_init\r
306 * NAME\r
307 *       cl_list_init\r
308 *\r
309 * DESCRIPTION\r
310 *       The cl_list_init function initializes a list for use.\r
311 *\r
312 * SYNOPSIS\r
313 */\r
314 CL_EXPORT cl_status_t CL_API\r
315 cl_list_init(\r
316         IN      cl_list_t* const        p_list,\r
317         IN      const size_t            min_items );\r
318 /*\r
319 * PARAMETERS\r
320 *       p_list\r
321 *               [in] Pointer to cl_list_t structure to initialize.\r
322 *\r
323 *       min_items\r
324 *               [in] Minimum number of items that can be stored.  All necessary\r
325 *               allocations to allow storing the minimum number of items is performed\r
326 *               at initialization time.\r
327 *\r
328 * RETURN VALUES\r
329 *       CL_SUCCESS if the list was initialized successfully.\r
330 *\r
331 *       CL_INSUFFICIENT_MEMORY if there was not enough memory for initialization.\r
332 *\r
333 * NOTES\r
334 *       The list will always be able to store at least as many items as specified\r
335 *       by the min_items parameter.\r
336 *\r
337 * SEE ALSO\r
338 *       List, cl_list_construct, cl_list_destroy, cl_list_insert_head,\r
339 *       cl_list_insert_tail, cl_list_remove_head, cl_list_remove_tail\r
340 *********/\r
341 \r
342 \r
343 /****f* Component Library: List/cl_list_destroy\r
344 * NAME\r
345 *       cl_list_destroy\r
346 *\r
347 * DESCRIPTION\r
348 *       The cl_list_destroy function destroys a list.\r
349 *\r
350 * SYNOPSIS\r
351 */\r
352 CL_EXPORT void CL_API\r
353 cl_list_destroy(\r
354         IN      cl_list_t* const        p_list );\r
355 /*\r
356 * PARAMETERS\r
357 *       p_list\r
358 *               [in] Pointer to cl_list_t structure to destroy.\r
359 *\r
360 * RETURN VALUE\r
361 *       This function does not return a value.\r
362 *\r
363 * NOTES\r
364 *       cl_list_destroy does not affect any of the objects stored in the list,\r
365 *       but does release all memory allocated internally.  Further operations\r
366 *       should not be attempted on the list after cl_list_destroy is invoked.\r
367 *\r
368 *       This function should only be called after a call to cl_list_construct\r
369 *       or cl_list_init.\r
370 *\r
371 *       In debug builds, cl_list_destroy asserts if the list is not empty.\r
372 *\r
373 * SEE ALSO\r
374 *       List, cl_list_construct, cl_list_init\r
375 *********/\r
376 \r
377 \r
378 /****f* Component Library: List/cl_is_list_empty\r
379 * NAME\r
380 *       cl_is_list_empty\r
381 *\r
382 * DESCRIPTION\r
383 *       The cl_is_list_empty function returns whether a list is empty.\r
384 *\r
385 * SYNOPSIS\r
386 */\r
387 CL_INLINE boolean_t CL_API\r
388 cl_is_list_empty(\r
389         IN      const cl_list_t* const  p_list )\r
390 {\r
391         CL_ASSERT( p_list );\r
392         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
393         return( cl_is_qlist_empty( &p_list->list ) );\r
394 }\r
395 /*\r
396 * PARAMETERS\r
397 *       p_list\r
398 *               [in] Pointer to a cl_list_t structure.\r
399 *\r
400 * RETURN VALUES\r
401 *       TRUE if the specified list is empty.\r
402 *\r
403 *       FALSE otherwise.\r
404 *\r
405 * SEE ALSO\r
406 *       List, cl_list_count, cl_list_remove_all\r
407 *********/\r
408 \r
409 \r
410 /****f* Component Library: List/cl_list_insert_head\r
411 * NAME\r
412 *       cl_list_insert_head\r
413 *\r
414 * DESCRIPTION\r
415 *       The cl_list_insert_head function inserts an object at the head of a list.\r
416 *\r
417 * SYNOPSIS\r
418 */\r
419 CL_INLINE cl_status_t CL_API\r
420 cl_list_insert_head(\r
421         IN      cl_list_t* const        p_list,\r
422         IN      const void* const       p_object )\r
423 {\r
424         cl_pool_obj_t   *p_pool_obj;\r
425 \r
426         CL_ASSERT( p_list );\r
427         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
428 \r
429         /* Get a list item to add to the list. */\r
430         p_pool_obj = (cl_pool_obj_t*)cl_qpool_get( &p_list->list_item_pool );\r
431         if( !p_pool_obj )\r
432                 return( CL_INSUFFICIENT_MEMORY );\r
433 \r
434         p_pool_obj->list_obj.p_object = p_object;\r
435         cl_qlist_insert_head( &p_list->list, &p_pool_obj->list_obj.list_item );\r
436         return( CL_SUCCESS );\r
437 }\r
438 /*\r
439 * PARAMETERS\r
440 *       p_list\r
441 *               [in] Pointer to a cl_list_t structure into which to insert the object.\r
442 *\r
443 *       p_object\r
444 *               [in] Pointer to an object to insert into the list.\r
445 *\r
446 * RETURN VALUES\r
447 *       CL_SUCCESS if the insertion was successful.\r
448 *\r
449 *       CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.\r
450 *\r
451 * NOTES\r
452 *       Inserts the specified object at the head of the list.  List insertion\r
453 *       operations are guaranteed to work for the minimum number of items as\r
454 *       specified in cl_list_init by the min_items parameter.\r
455 *\r
456 * SEE ALSO\r
457 *       List, cl_list_insert_tail, cl_list_insert_array_head,\r
458 *       cl_list_insert_array_tail, cl_list_insert_prev, cl_list_insert_next,\r
459 *       cl_list_remove_head\r
460 *********/\r
461 \r
462 \r
463 /****f* Component Library: List/cl_list_insert_tail\r
464 * NAME\r
465 *       cl_list_insert_tail\r
466 *\r
467 * DESCRIPTION\r
468 *       The cl_list_insert_tail function inserts an object at the head of a list.\r
469 *\r
470 * SYNOPSIS\r
471 */\r
472 CL_INLINE cl_status_t CL_API\r
473 cl_list_insert_tail(\r
474         IN      cl_list_t* const        p_list,\r
475         IN      const void* const       p_object )\r
476 {\r
477         cl_pool_obj_t   *p_pool_obj;\r
478 \r
479         CL_ASSERT( p_list );\r
480         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
481 \r
482         /* Get a list item to add to the list. */\r
483         p_pool_obj = (cl_pool_obj_t*)cl_qpool_get( &p_list->list_item_pool );\r
484         if( !p_pool_obj )\r
485                 return( CL_INSUFFICIENT_MEMORY );\r
486 \r
487         p_pool_obj->list_obj.p_object = p_object;\r
488         cl_qlist_insert_tail( &p_list->list, &p_pool_obj->list_obj.list_item );\r
489         return( CL_SUCCESS );\r
490 }\r
491 /*\r
492 * PARAMETERS\r
493 *       p_list\r
494 *               [in] Pointer to a cl_list_t structure into which to insert the object.\r
495 *\r
496 *       p_object\r
497 *               [in] Pointer to an object to insert into the list.\r
498 *\r
499 * RETURN VALUES\r
500 *       CL_SUCCESS if the insertion was successful.\r
501 *\r
502 *       CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.\r
503 *\r
504 * NOTES\r
505 *       Inserts the specified object at the tail of the list.  List insertion\r
506 *       operations are guaranteed to work for the minimum number of items as\r
507 *       specified in cl_list_init by the min_items parameter.\r
508 *\r
509 * SEE ALSO\r
510 *       List, cl_list_insert_head, cl_list_insert_array_head,\r
511 *       cl_list_insert_array_tail, cl_list_insert_prev, cl_list_insert_next,\r
512 *       cl_list_remove_tail\r
513 *********/\r
514 \r
515 \r
516 /****f* Component Library: List/cl_list_insert_array_head\r
517 * NAME\r
518 *       cl_list_insert_array_head\r
519 *\r
520 * DESCRIPTION:\r
521 *       The cl_list_insert_array_head function inserts an array of objects\r
522 *       at the head of a list.\r
523 *\r
524 * SYNOPSIS\r
525 */\r
526 CL_EXPORT cl_status_t CL_API\r
527 cl_list_insert_array_head(\r
528         IN      cl_list_t* const        p_list,\r
529         IN      const void* const       p_array,\r
530         IN      uint32_t                        item_count,\r
531         IN      const uint32_t          item_size );\r
532 /*\r
533 * PARAMETERS\r
534 *       p_list\r
535 *               [in] Pointer to a cl_list_t structure into which to insert the objects.\r
536 *\r
537 *       p_array\r
538 *               [in] Pointer to the first object in an array.\r
539 *\r
540 *       item_count\r
541 *               [in] Number of objects in the array.\r
542 *\r
543 *       item_size\r
544 *               [in] Size of the objects added to the list.  This is the stride in the\r
545 *               array from one object to the next.\r
546 *\r
547 * RETURN VALUES\r
548 *       CL_SUCCESS if the insertion was successful.\r
549 *\r
550 *       CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.\r
551 *\r
552 * NOTES\r
553 *       Inserts all objects in the array to the head of the list, preserving the\r
554 *       ordering of the objects.  If not successful, no items are added.\r
555 *       List insertion operations are guaranteed to work for the minimum number\r
556 *       of items as specified in cl_list_init by the min_items parameter.\r
557 *\r
558 * SEE ALSO\r
559 *       List, cl_list_insert_array_tail, cl_list_insert_head, cl_list_insert_tail,\r
560 *       cl_list_insert_prev, cl_list_insert_next\r
561 *********/\r
562 \r
563 \r
564 /****f* Component Library: List/cl_list_insert_array_tail\r
565 * NAME\r
566 *       cl_list_insert_array_tail\r
567 *\r
568 * DESCRIPTION\r
569 *       The cl_list_insert_array_tail function inserts an array of objects\r
570 *       at the tail of a list.\r
571 *\r
572 * SYNOPSIS\r
573 */\r
574 CL_EXPORT cl_status_t CL_API\r
575 cl_list_insert_array_tail(\r
576         IN      cl_list_t* const        p_list,\r
577         IN      const void* const       p_array,\r
578         IN      uint32_t                        item_count,\r
579         IN      const uint32_t          item_size);\r
580 /*\r
581 * PARAMETERS\r
582 *       p_list\r
583 *               [in] Pointer to a cl_list_t structure into which to insert the objects.\r
584 *\r
585 *       p_array\r
586 *               [in] Pointer to the first object in an array.\r
587 *\r
588 *       item_count\r
589 *               [in] Number of objects in the array.\r
590 *\r
591 *       item_size\r
592 *               [in] Size of the objects added to the list.  This is the stride in the\r
593 *               array from one object to the next.\r
594 *\r
595 * RETURN VALUES\r
596 *       CL_SUCCESS if the insertion was successful.\r
597 *\r
598 *       CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.\r
599 *\r
600 * NOTES\r
601 *       Inserts all objects in the array to the tail of the list, preserving the\r
602 *       ordering of the objects.  If not successful, no items are added.\r
603 *       List insertion operations are guaranteed to work for the minimum number\r
604 *       of items as specified in cl_list_init by the min_items parameter.\r
605 *\r
606 * SEE ALSO\r
607 *       List, cl_list_insert_array_head, cl_list_insert_head, cl_list_insert_tail,\r
608 *       cl_list_insert_prev, cl_list_insert_next\r
609 *********/\r
610 \r
611 \r
612 /****f* Component Library: List/cl_list_insert_next\r
613 * NAME\r
614 *       cl_list_insert_next\r
615 *\r
616 * DESCRIPTION\r
617 *       The cl_list_insert_next function inserts an object in a list after\r
618 *       the object associated with a given iterator.\r
619 *\r
620 * SYNOPSIS\r
621 */\r
622 CL_INLINE cl_status_t CL_API\r
623 cl_list_insert_next(\r
624         IN      cl_list_t* const                        p_list,\r
625         IN      const cl_list_iterator_t        iterator,\r
626         IN      const void* const                       p_object )\r
627 {\r
628         cl_pool_obj_t   *p_pool_obj;\r
629 \r
630         CL_ASSERT( p_list );\r
631         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
632 \r
633         /* Get a list item to add to the list. */\r
634         p_pool_obj = (cl_pool_obj_t*)cl_qpool_get( &p_list->list_item_pool );\r
635         if( !p_pool_obj )\r
636                 return( CL_INSUFFICIENT_MEMORY );\r
637 \r
638         p_pool_obj->list_obj.p_object = p_object;\r
639         cl_qlist_insert_next( &p_list->list, (cl_list_item_t*)iterator,\r
640                 &p_pool_obj->list_obj.list_item );\r
641         return( CL_SUCCESS );\r
642 }\r
643 /*\r
644 * PARAMETERS\r
645 *       p_list\r
646 *               [in] Pointer to a cl_list_t structure into which to insert the object.\r
647 *\r
648 *       iterator\r
649 *               [in] cl_list_iterator_t returned by a previous call to cl_list_head,\r
650 *               cl_list_tail, cl_list_next, or cl_list_prev.\r
651 *\r
652 *       p_object\r
653 *               [in] Pointer to an object to insert into the list.\r
654 *\r
655 * RETURN VALUES\r
656 *       CL_SUCCESS if the insertion was successful.\r
657 *\r
658 *       CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.\r
659 *\r
660 * SEE ALSO\r
661 *       List, cl_list_insert_prev, cl_list_insert_head, cl_list_insert_tail,\r
662 *       cl_list_insert_array_head, cl_list_insert_array_tail\r
663 *********/\r
664 \r
665 \r
666 \r
667 /****f* Component Library: List/cl_list_insert_prev\r
668 * NAME\r
669 *       cl_list_insert_prev\r
670 *\r
671 * DESCRIPTION\r
672 *       The cl_list_insert_prev function inserts an object in a list before\r
673 *       the object associated with a given iterator.\r
674 *\r
675 * SYNOPSIS\r
676 */\r
677 CL_INLINE cl_status_t CL_API\r
678 cl_list_insert_prev(\r
679         IN      cl_list_t* const                        p_list,\r
680         IN      const cl_list_iterator_t        iterator,\r
681         IN      const void* const                       p_object )\r
682 {\r
683         cl_pool_obj_t   *p_pool_obj;\r
684 \r
685         CL_ASSERT( p_list );\r
686         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
687 \r
688         /* Get a list item to add to the list. */\r
689         p_pool_obj = (cl_pool_obj_t*)cl_qpool_get( &p_list->list_item_pool );\r
690         if( !p_pool_obj )\r
691                 return( CL_INSUFFICIENT_MEMORY );\r
692 \r
693         p_pool_obj->list_obj.p_object = p_object;\r
694         cl_qlist_insert_prev( &p_list->list, (cl_list_item_t*)iterator,\r
695                 &p_pool_obj->list_obj.list_item );\r
696         return( CL_SUCCESS );\r
697 }\r
698 /*\r
699 * PARAMETERS\r
700 *       p_list\r
701 *               [in] Pointer to a cl_list_t structure into which to insert the object.\r
702 *\r
703 *       iterator\r
704 *               [in] cl_list_iterator_t returned by a previous call to cl_list_head,\r
705 *               cl_list_tail, cl_list_next, or cl_list_prev.\r
706 *\r
707 *       p_object\r
708 *               [in] Pointer to an object to insert into the list.\r
709 *\r
710 * RETURN VALUES\r
711 *       CL_SUCCESS if the insertion was successful.\r
712 *\r
713 *       CL_INSUFFICIENT_MEMORY if there was not enough memory for the insertion.\r
714 *\r
715 * SEE ALSO\r
716 *       List, cl_list_insert_next, cl_list_insert_head, cl_list_insert_tail,\r
717 *       cl_list_insert_array_head, cl_list_insert_array_tail\r
718 *********/\r
719 \r
720 \r
721 /****f* Component Library: List/cl_list_remove_head\r
722 * NAME\r
723 *       cl_list_remove_head\r
724 *\r
725 * DESCRIPTION\r
726 *       The cl_list_remove_head function removes an object from the head of a list.\r
727 *\r
728 * SYNOPSIS\r
729 */\r
730 CL_INLINE void* CL_API\r
731 cl_list_remove_head(\r
732         IN      cl_list_t* const        p_list )\r
733 {\r
734         cl_pool_obj_t   *p_pool_obj;\r
735 \r
736         CL_ASSERT( p_list );\r
737         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
738 \r
739         /* See if the list is empty. */\r
740         if( cl_is_qlist_empty( &p_list->list ) )\r
741                 return( NULL );\r
742 \r
743         /* Get the item at the head of the list. */\r
744         p_pool_obj = (cl_pool_obj_t*)cl_qlist_remove_head( &p_list->list );\r
745 \r
746         /* Place the pool item back into the pool. */\r
747         cl_qpool_put( &p_list->list_item_pool, (cl_pool_item_t*)p_pool_obj );\r
748 \r
749         return( (void*)p_pool_obj->list_obj.p_object );\r
750 }\r
751 /*\r
752 * PARAMETERS\r
753 *       p_list\r
754 *               [in] Pointer to a cl_list_t structure from which to remove an object.\r
755 *\r
756 * RETURN VALUES\r
757 *       Returns the pointer to the object formerly at the head of the list.\r
758 *\r
759 *       NULL if the list was empty.\r
760 *\r
761 * SEE ALSO\r
762 *       List, cl_list_remove_tail, cl_list_remove_all, cl_list_remove_object,\r
763 *       cl_list_remove_item, cl_list_insert_head\r
764 *********/\r
765 \r
766 \r
767 /****f* Component Library: List/cl_list_remove_tail\r
768 * NAME\r
769 *       cl_list_remove_tail\r
770 *\r
771 * DESCRIPTION\r
772 *       The cl_list_remove_tail function removes an object from the tail of a list.\r
773 *\r
774 * SYNOPSIS\r
775 */\r
776 CL_INLINE void* CL_API\r
777 cl_list_remove_tail(\r
778         IN      cl_list_t* const        p_list )\r
779 {\r
780         cl_pool_obj_t   *p_pool_obj;\r
781 \r
782         CL_ASSERT( p_list );\r
783         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
784 \r
785         /* See if the list is empty. */\r
786         if( cl_is_qlist_empty( &p_list->list ) )\r
787                 return( NULL );\r
788 \r
789         /* Get the item at the head of the list. */\r
790         p_pool_obj = (cl_pool_obj_t*)cl_qlist_remove_tail( &p_list->list );\r
791 \r
792         /* Place the list item back into the pool. */\r
793         cl_qpool_put( &p_list->list_item_pool, (cl_pool_item_t*)p_pool_obj );\r
794 \r
795         return( (void*)p_pool_obj->list_obj.p_object );\r
796 }\r
797 /*\r
798 * PARAMETERS\r
799 *       p_list\r
800 *               [in] Pointer to a cl_list_t structure from which to remove an object.\r
801 *\r
802 * RETURN VALUES\r
803 *       Returns the pointer to the object formerly at the tail of the list.\r
804 *\r
805 *       NULL if the list was empty.\r
806 *\r
807 * SEE ALSO\r
808 *       List, cl_list_remove_head, cl_list_remove_all, cl_list_remove_object,\r
809 *       cl_list_remove_item, cl_list_insert_head\r
810 *********/\r
811 \r
812 \r
813 /****f* Component Library: List/cl_list_remove_all\r
814 * NAME\r
815 *       cl_list_remove_all\r
816 *\r
817 * DESCRIPTION\r
818 *       The cl_list_remove_all function removes all objects from a list,\r
819 *       leaving it empty.\r
820 *\r
821 * SYNOPSIS\r
822 */\r
823 CL_INLINE void CL_API\r
824 cl_list_remove_all(\r
825         IN      cl_list_t* const        p_list )\r
826 {\r
827         CL_ASSERT( p_list );\r
828         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
829 \r
830         /* Return all the list items to the pool. */\r
831         cl_qpool_put_list( &p_list->list_item_pool, &p_list->list );\r
832 }\r
833 /*\r
834 * PARAMETERS\r
835 *       p_list\r
836 *               [in] Pointer to a cl_list_t structure from which to remove all objects.\r
837 *\r
838 * RETURN VALUE\r
839 *       This function does not return a value.\r
840 *\r
841 * SEE ALSO\r
842 *       List, cl_list_remove_head, cl_list_remove_tail, cl_list_remove_object,\r
843 *       cl_list_remove_item\r
844 *********/\r
845 \r
846 \r
847 /****f* Component Library: List/cl_list_remove_object\r
848 * NAME\r
849 *       cl_list_remove_object\r
850 *\r
851 * DESCRIPTION\r
852 *       The cl_list_remove_object function removes a specific object from a list.\r
853 *\r
854 * SYNOPSIS\r
855 */\r
856 CL_EXPORT cl_status_t CL_API\r
857 cl_list_remove_object(\r
858         IN      cl_list_t* const        p_list,\r
859         IN      const void* const       p_object );\r
860 /*\r
861 * PARAMETERS\r
862 *       p_list\r
863 *               [in] Pointer to a cl_list_t structure from which to remove the object.\r
864 *\r
865 *       p_object\r
866 *               [in] Pointer to an object to remove from the list.\r
867 *\r
868 * RETURN VALUES\r
869 *       CL_SUCCESS if the object was removed.\r
870 *\r
871 *       CL_NOT_FOUND if the object was not found in the list.\r
872 *\r
873 * NOTES\r
874 *       Removes the first occurrence of an object from a list.\r
875 *\r
876 * SEE ALSO\r
877 *       List, cl_list_remove_item, cl_list_remove_head, cl_list_remove_tail,\r
878 *       cl_list_remove_all\r
879 *********/\r
880 \r
881 \r
882 /****f* Component Library: List/cl_list_remove_item\r
883 * NAME\r
884 *       cl_list_remove_item\r
885 *\r
886 * DESCRIPTION\r
887 *       The cl_list_remove_item function removes an object from the head of a list.\r
888 *\r
889 * SYNOPSIS\r
890 */\r
891 CL_INLINE void CL_API\r
892 cl_list_remove_item(\r
893         IN      cl_list_t* const                        p_list,\r
894         IN      const cl_list_iterator_t        iterator )\r
895 {\r
896         CL_ASSERT( p_list );\r
897         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
898 \r
899         cl_qlist_remove_item( &p_list->list, (cl_list_item_t*)iterator );\r
900 \r
901         /* Place the list item back into the pool. */\r
902         cl_qpool_put( &p_list->list_item_pool, (cl_pool_item_t*)iterator );\r
903 }\r
904 /*\r
905 * PARAMETERS\r
906 *       p_list\r
907 *               [in] Pointer to a cl_list_t structure from which to remove the item.\r
908 *\r
909 *       iterator\r
910 *               [in] cl_list_iterator_t returned by a previous call to cl_list_head,\r
911 *               cl_list_tail, cl_list_next, or cl_list_prev.\r
912 *\r
913 * RETURN VALUE\r
914 *       This function does not return a value.\r
915 *\r
916 * SEE ALSO\r
917 *       List, cl_list_remove_object, cl_list_remove_head, cl_list_remove_tail,\r
918 *       cl_list_remove_all\r
919 *********/\r
920 \r
921 \r
922 /****f* Component Library: List/cl_is_object_in_list\r
923 * NAME\r
924 *       cl_is_object_in_list\r
925 *\r
926 * DESCRIPTION\r
927 *       The cl_is_object_in_list function returns whether an object\r
928 *       is stored in a list.\r
929 *\r
930 * SYNOPSIS\r
931 */\r
932 CL_EXPORT boolean_t CL_API\r
933 cl_is_object_in_list(\r
934         IN      const cl_list_t* const  p_list,\r
935         IN      const void* const               p_object );\r
936 /*\r
937 * PARAMETERS\r
938 *       p_list\r
939 *               [in] Pointer to a cl_list_t structure in which to look for the object.\r
940 *\r
941 *       p_object\r
942 *               [in] Pointer to an object stored in a list.\r
943 *\r
944 * RETURN VALUES\r
945 *       TRUE if p_object was found in the list.\r
946 *\r
947 *       FALSE otherwise.\r
948 *\r
949 * SEE ALSO\r
950 *       List\r
951 *********/\r
952 \r
953 \r
954 /****f* Component Library: List/cl_list_end\r
955 * NAME\r
956 *       cl_list_end\r
957 *\r
958 * DESCRIPTION\r
959 *       The cl_list_end function returns returns the list iterator for\r
960 *       the end of a list.\r
961 *\r
962 * SYNOPSIS\r
963 */\r
964 CL_INLINE const cl_list_iterator_t CL_API\r
965 cl_list_end(\r
966         IN      const cl_list_t* const  p_list )\r
967 {\r
968         CL_ASSERT( p_list );\r
969         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
970 \r
971         return( cl_qlist_end( &p_list->list ) );\r
972 }\r
973 /*\r
974 * PARAMETERS\r
975 *       p_list\r
976 *               [in] Pointer to a cl_list_t structure for which the iterator for the\r
977 *               object at the head is to be returned.\r
978 *\r
979 * RETURN VALUE\r
980 *       cl_list_iterator_t for the end of the list.\r
981 *\r
982 * NOTES\r
983 *       Use cl_list_obj to retrieve the object associated with the\r
984 *       returned cl_list_iterator_t.\r
985 *\r
986 * SEE ALSO\r
987 *       List, cl_list_head, cl_list_tail, cl_list_next, cl_list_prev,\r
988 *       cl_list_obj\r
989 *********/\r
990 \r
991 \r
992 /****f* Component Library: List/cl_list_head\r
993 * NAME\r
994 *       cl_list_head\r
995 *\r
996 * DESCRIPTION\r
997 *       The cl_list_head function returns returns a list iterator for\r
998 *       the head of a list.\r
999 *\r
1000 * SYNOPSIS\r
1001 */\r
1002 CL_INLINE const cl_list_iterator_t CL_API\r
1003 cl_list_head(\r
1004         IN      const cl_list_t* const  p_list )\r
1005 {\r
1006         CL_ASSERT( p_list );\r
1007         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
1008 \r
1009         return( cl_qlist_head( &p_list->list ) );\r
1010 }\r
1011 /*\r
1012 * PARAMETERS\r
1013 *       p_list\r
1014 *               [in] Pointer to a cl_list_t structure for which the iterator for the\r
1015 *               object at the head is to be returned.\r
1016 *\r
1017 * RETURN VALUES\r
1018 *       cl_list_iterator_t for the head of the list.\r
1019 *\r
1020 *       cl_list_iterator_t for the end of the list if the list is empty.\r
1021 *\r
1022 * NOTES\r
1023 *       Use cl_list_obj to retrieve the object associated with the\r
1024 *       returned cl_list_iterator_t.\r
1025 *\r
1026 * SEE ALSO\r
1027 *       List, cl_list_tail, cl_list_next, cl_list_prev, cl_list_end,\r
1028 *       cl_list_obj\r
1029 *********/\r
1030 \r
1031 \r
1032 /****f* Component Library: List/cl_list_tail\r
1033 * NAME\r
1034 *       cl_list_tail\r
1035 *\r
1036 * DESCRIPTION\r
1037 *       The cl_list_tail function returns returns a list iterator for\r
1038 *       the tail of a list.\r
1039 *\r
1040 * SYNOPSIS\r
1041 */\r
1042 CL_INLINE const cl_list_iterator_t CL_API\r
1043 cl_list_tail(\r
1044         IN      const cl_list_t* const  p_list )\r
1045 {\r
1046         CL_ASSERT( p_list );\r
1047         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
1048 \r
1049         return( cl_qlist_tail( &p_list->list ) );\r
1050 }\r
1051 /*\r
1052 * PARAMETERS\r
1053 *       p_list\r
1054 *               [in] Pointer to a cl_list_t structure for which the iterator for the\r
1055 *               object at the tail is to be returned.\r
1056 *\r
1057 * RETURN VALUES\r
1058 *       cl_list_iterator_t for the tail of the list.\r
1059 *\r
1060 *       cl_list_iterator_t for the end of the list if the list is empty.\r
1061 *\r
1062 * NOTES\r
1063 *       Use cl_list_obj to retrieve the object associated with the\r
1064 *\r
1065 *       returned cl_list_iterator_t.\r
1066 *\r
1067 * SEE ALSO\r
1068 *       List, cl_list_head, cl_list_next, cl_list_prev, cl_list_end,\r
1069 *       cl_list_obj\r
1070 *********/\r
1071 \r
1072 \r
1073 /****f* Component Library: List/cl_list_next\r
1074 * NAME\r
1075 *       cl_list_next\r
1076 *\r
1077 * DESCRIPTION\r
1078 *       The cl_list_next function returns a list iterator for the object stored\r
1079 *       in a list after the object associated with a given list iterator.\r
1080 *\r
1081 * SYNOPSIS\r
1082 */\r
1083 CL_INLINE const cl_list_iterator_t CL_API\r
1084 cl_list_next(\r
1085         IN      const cl_list_iterator_t        iterator )\r
1086 {\r
1087         CL_ASSERT( iterator );\r
1088 \r
1089         return( cl_qlist_next( iterator ) );\r
1090 }\r
1091 /*\r
1092 * PARAMETERS\r
1093 *       p_list\r
1094 *               [in] Pointer to a cl_list_t structure for which the iterator for the\r
1095 *               next object is to be returned.\r
1096 *\r
1097 *       iterator\r
1098 *               [in] cl_list_iterator_t returned by a previous call to cl_list_head,\r
1099 *               cl_list_tail, cl_list_next, or cl_list_prev.\r
1100 *\r
1101 * RETURN VALUES\r
1102 *       cl_list_iterator_t for the object following the object associated with\r
1103 *       the list iterator specified by the iterator parameter.\r
1104 *\r
1105 *       cl_list_iterator_t for the end of the list if the list is empty.\r
1106 *\r
1107 * NOTES\r
1108 *       Use cl_list_obj to retrieve the object associated with the\r
1109 *       returned cl_list_iterator_t.\r
1110 *\r
1111 * SEE ALSO\r
1112 *       List, cl_list_prev, cl_list_head, cl_list_tail, cl_list_end,\r
1113 *       cl_list_obj\r
1114 *********/\r
1115 \r
1116 \r
1117 /****f* Component Library: List/cl_list_prev\r
1118 * NAME\r
1119 *       cl_list_prev\r
1120 *\r
1121 * DESCRIPTION\r
1122 *       The cl_list_prev function returns a list iterator for the object stored\r
1123 *       in a list before the object associated with a given list iterator.\r
1124 *\r
1125 * SYNOPSIS\r
1126 */\r
1127 CL_INLINE const cl_list_iterator_t CL_API\r
1128 cl_list_prev(\r
1129         IN      const cl_list_iterator_t        iterator )\r
1130 {\r
1131         CL_ASSERT( iterator );\r
1132 \r
1133         return( cl_qlist_prev( iterator ) );\r
1134 }\r
1135 /*\r
1136 * PARAMETERS\r
1137 *       p_list\r
1138 *               [in] Pointer to a cl_list_t structure for which the iterator for the\r
1139 *               next object is to be returned.\r
1140 *\r
1141 *       iterator\r
1142 *               [in] cl_list_iterator_t returned by a previous call to cl_list_head,\r
1143 *               cl_list_tail, cl_list_next, or cl_list_prev.\r
1144 *\r
1145 * RETURN VALUES\r
1146 *       cl_list_iterator_t for the object preceding the object associated with\r
1147 *       the list iterator specified by the iterator parameter.\r
1148 *\r
1149 *       cl_list_iterator_t for the end of the list if the list is empty.\r
1150 *\r
1151 * NOTES\r
1152 *       Use cl_list_obj to retrieve the object associated with the\r
1153 *       returned cl_list_iterator_t.\r
1154 *\r
1155 * SEE ALSO\r
1156 *       List, cl_list_next, cl_list_head, cl_list_tail, cl_list_end,\r
1157 *       cl_list_obj\r
1158 *********/\r
1159 \r
1160 \r
1161 /****f* Component Library: List/cl_list_obj\r
1162 * NAME\r
1163 *       cl_list_obj\r
1164 *\r
1165 * DESCRIPTION\r
1166 *       The cl_list_obj function returns the object associated\r
1167 *       with a list iterator.\r
1168 *\r
1169 * SYNOPSIS\r
1170 */\r
1171 CL_INLINE void* CL_API\r
1172 cl_list_obj(\r
1173         IN      const cl_list_iterator_t        iterator )\r
1174 {\r
1175         CL_ASSERT( iterator );\r
1176 \r
1177         return( (void*)((cl_pool_obj_t*)iterator)->list_obj.p_object );\r
1178 }\r
1179 /*\r
1180 * PARAMETERS\r
1181 *       iterator\r
1182 *               [in] cl_list_iterator_t returned by a previous call to cl_list_head,\r
1183 *               cl_list_tail, cl_list_next, or cl_list_prev whose object is requested.\r
1184 *\r
1185 * RETURN VALUE\r
1186 *       Pointer to the object associated with the list iterator specified\r
1187 *       by the iterator parameter.\r
1188 *\r
1189 * SEE ALSO\r
1190 *       List, cl_list_head, cl_list_tail, cl_list_next, cl_list_prev\r
1191 *********/\r
1192 \r
1193 \r
1194 /****f* Component Library: List/cl_list_find_from_head\r
1195 * NAME\r
1196 *       cl_list_find_from_head\r
1197 *\r
1198 * DESCRIPTION\r
1199 *       The cl_list_find_from_head function uses a specified function\r
1200 *       to search for an object starting from the head of a list.\r
1201 *\r
1202 * SYNOPSIS\r
1203 */\r
1204 CL_EXPORT const cl_list_iterator_t CL_API\r
1205 cl_list_find_from_head(\r
1206         IN      const cl_list_t* const  p_list,\r
1207         IN      cl_pfn_list_find_t              pfn_func,\r
1208         IN      const void* const               context );\r
1209 /*\r
1210 * PARAMETERS\r
1211 *       p_list\r
1212 *               [in] Pointer to a cl_list_t structure to search.\r
1213 *\r
1214 *       pfn_func\r
1215 *               [in] Function invoked to determine if a match was found.\r
1216 *               See the cl_pfn_list_find_t function type declaration for details\r
1217 *               about the callback function.\r
1218 *\r
1219 *       context\r
1220 *               [in] Value to pass to the callback functions to provide context.\r
1221 *\r
1222 * RETURN VALUES\r
1223 *       Returns the iterator for the object if found.\r
1224 *\r
1225 *       Returns the iterator for the list end otherwise.\r
1226 *\r
1227 * NOTES\r
1228 *       cl_list_find_from_head does not remove the found object from\r
1229 *       the list.  The iterator for the object is returned when the function\r
1230 *       provided by the pfn_func parameter returns CL_SUCCESS.  The function\r
1231 *       specified by the pfn_func parameter must not perform any list\r
1232 *       operations as these would corrupt the list.\r
1233 *\r
1234 * SEE ALSO\r
1235 *       List, cl_list_find_from_tail, cl_list_apply_func,\r
1236 *       cl_pfn_list_find_t\r
1237 *********/\r
1238 \r
1239 \r
1240 /****f* Component Library: List/cl_list_find_from_tail\r
1241 * NAME\r
1242 *       cl_list_find_from_tail\r
1243 *\r
1244 * DESCRIPTION\r
1245 *       The cl_list_find_from_tail function uses a specified function\r
1246 *       to search for an object starting from the tail of a list.\r
1247 *\r
1248 * SYNOPSIS\r
1249 */\r
1250 CL_EXPORT const cl_list_iterator_t CL_API\r
1251 cl_list_find_from_tail(\r
1252         IN      const cl_list_t* const  p_list,\r
1253         IN      cl_pfn_list_find_t              pfn_func,\r
1254         IN      const void* const               context );\r
1255 /*\r
1256 * PARAMETERS\r
1257 *       p_list\r
1258 *               [in] Pointer to a cl_list_t structure to search.\r
1259 *\r
1260 *       pfn_func\r
1261 *               [in] Function invoked to determine if a match was found.\r
1262 *               See the cl_pfn_list_find_t function type declaration for details\r
1263 *               about the callback function.\r
1264 *\r
1265 *       context\r
1266 *               [in] Value to pass to the callback functions to provide context.\r
1267 *\r
1268 * RETURN VALUES\r
1269 *       Returns the iterator for the object if found.\r
1270 *\r
1271 *       Returns the iterator for the list end otherwise.\r
1272 *\r
1273 * NOTES\r
1274 *       cl_list_find_from_tail does not remove the found object from\r
1275 *       the list.  The iterator for the object is returned when the function\r
1276 *       provided by the pfn_func parameter returns CL_SUCCESS.  The function\r
1277 *       specified by the pfn_func parameter must not perform any list\r
1278 *       operations as these would corrupt the list.\r
1279 *\r
1280 * SEE ALSO\r
1281 *       List, cl_list_find_from_head, cl_list_apply_func,\r
1282 *       cl_pfn_list_find_t\r
1283 *********/\r
1284 \r
1285 \r
1286 /****f* Component Library: List/cl_list_apply_func\r
1287 * NAME\r
1288 *       cl_list_apply_func\r
1289 *\r
1290 * DESCRIPTION\r
1291 *       The cl_list_apply_func function executes a specified function for every\r
1292 *       object stored in a list.\r
1293 *\r
1294 * SYNOPSIS\r
1295 */\r
1296 CL_EXPORT void CL_API\r
1297 cl_list_apply_func(\r
1298         IN      const cl_list_t* const  p_list,\r
1299         IN      cl_pfn_list_apply_t             pfn_func,\r
1300         IN      const void* const               context );\r
1301 /*\r
1302 * PARAMETERS\r
1303 *       p_list\r
1304 *               [in] Pointer to a cl_list_t structure to iterate.\r
1305 *\r
1306 *       pfn_func\r
1307 *               [in] Function invoked for every item in a list.\r
1308 *               See the cl_pfn_list_apply_t function type declaration for details\r
1309 *               about the callback function.\r
1310 *\r
1311 *       context\r
1312 *               [in] Value to pass to the callback functions to provide context.\r
1313 *\r
1314 * RETURN VALUE\r
1315 *       This function does not return a value.\r
1316 *\r
1317 * NOTES\r
1318 *       cl_list_apply_func invokes the specified callback function for every\r
1319 *       object stored in the list, starting from the head.  The function specified\r
1320 *       by the pfn_func parameter must not perform any list operations as these\r
1321 *       would corrupt the list.\r
1322 *\r
1323 * SEE ALSO\r
1324 *       List, cl_list_find_from_head, cl_list_find_from_tail,\r
1325 *       cl_pfn_list_apply_t\r
1326 *********/\r
1327 \r
1328 \r
1329 /****f* Component Library: List/cl_list_count\r
1330 * NAME\r
1331 *       cl_list_count\r
1332 *\r
1333 * DESCRIPTION\r
1334 *       The cl_list_count function returns the number of objects stored in a list.\r
1335 *\r
1336 * SYNOPSIS\r
1337 */\r
1338 CL_INLINE size_t CL_API\r
1339 cl_list_count(\r
1340         IN      const cl_list_t* const  p_list )\r
1341 {\r
1342         CL_ASSERT( p_list );\r
1343         CL_ASSERT( cl_is_qpool_inited( &p_list->list_item_pool ) );\r
1344 \r
1345         return( cl_qlist_count( &p_list->list ) );\r
1346 }\r
1347 /*\r
1348 * PARAMETERS\r
1349 *       p_list\r
1350 *               [in] Pointer to a cl_list_t structure whose object to count.\r
1351 *\r
1352 * RETURN VALUES\r
1353 *       Number of objects stored in the specified list.\r
1354 *\r
1355 * SEE ALSO\r
1356 *       List\r
1357 *********/\r
1358 \r
1359 \r
1360 #ifdef __cplusplus\r
1361 }       /* extern "C" */\r
1362 #endif\r
1363 \r
1364 #endif /* _CL_LIST_H_ */\r