[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_qlist.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 quick list.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_QUICK_LIST_H_\r
44 #define _CL_QUICK_LIST_H_\r
45 \r
46 \r
47 #include <complib/cl_types.h>\r
48 \r
49 \r
50 /****h* Component Library/Quick List\r
51 * NAME\r
52 *       Quick List\r
53 *\r
54 * DESCRIPTION\r
55 *       Quick list implements a doubly linked that stores user provided\r
56 *       cl_list_item_t structures.\r
57 *       Quick list does not allocate any memory, and can therefore not fail any\r
58 *       operations.  Quick list can therefore be useful in minimizing the error\r
59 *       paths in code.\r
60 *\r
61 *       Quick list is not thread safe, and users must provide serialization when\r
62 *       adding and removing items from the list. Note that it is possible to\r
63 *       walk a quick list while simultaneously adding to it.\r
64 *\r
65 *       The Quick List functions operate on a cl_qlist_t structure which should be\r
66 *       treated as opaque and should be manipulated only through the provided\r
67 *       functions.\r
68 *\r
69 * SEE ALSO\r
70 *       Structures:\r
71 *               cl_qlist_t, cl_list_item_t, cl_list_obj_t\r
72 *\r
73 *       Callbacks:\r
74 *               cl_pfn_qlist_apply_t, cl_pfn_qlist_find_t\r
75 *\r
76 *       Item Manipulation:\r
77 *               cl_qlist_set_obj, cl_qlist_obj\r
78 *\r
79 *       Initialization:\r
80 *               cl_qlist_init\r
81 *\r
82 *       Iteration:\r
83 *               cl_qlist_next, cl_qlist_prev, cl_qlist_head, cl_qlist_tail,\r
84 *               cl_qlist_end\r
85 *\r
86 *       Manipulation:\r
87 *               cl_qlist_insert_head, cl_qlist_insert_tail,\r
88 *               cl_qlist_insert_list_head, cl_qlist_insert_list_tail,\r
89 *               cl_qlist_insert_array_head, cl_qlist_insert_array_tail,\r
90 *               cl_qlist_insert_prev, cl_qlist_insert_next,\r
91 *               cl_qlist_remove_head, cl_qlist_remove_tail,\r
92 *               cl_qlist_remove_item, cl_qlist_remove_all\r
93 *\r
94 *       Search:\r
95 *               cl_is_item_in_qlist, cl_qlist_find_next, cl_qlist_find_prev,\r
96 *               cl_qlist_find_from_head, cl_qlist_find_from_tail\r
97 *               cl_qlist_apply_func, cl_qlist_move_items\r
98 *\r
99 *       Attributes:\r
100 *               cl_qlist_count, cl_is_qlist_empty\r
101 *********/\r
102 \r
103 \r
104 /****s* Component Library: Quick List/cl_list_item_t\r
105 * NAME\r
106 *       cl_list_item_t\r
107 *\r
108 * DESCRIPTION\r
109 *       The cl_list_item_t structure is used by lists to store objects.\r
110 *\r
111 * SYNOPSIS\r
112 */\r
113 typedef struct _cl_list_item\r
114 {\r
115         struct _cl_list_item    *p_next;\r
116         struct _cl_list_item    *p_prev;\r
117 #ifdef _DEBUG_\r
118         struct _cl_qlist                *p_list;\r
119 #endif\r
120 \r
121 } cl_list_item_t;\r
122 /*\r
123 * FIELDS\r
124 *       p_next\r
125 *               Used internally by the list. Users should not use this field.\r
126 *\r
127 *       p_prev\r
128 *               Used internally by the list. Users should not use this field.\r
129 *\r
130 * SEE ALSO\r
131 *       Quick List\r
132 *********/\r
133 \r
134 \r
135 /****s* Component Library: Quick List/cl_list_obj_t\r
136 * NAME\r
137 *       cl_list_obj_t\r
138 *\r
139 * DESCRIPTION\r
140 *       The cl_list_obj_t structure is used by lists to store objects.\r
141 *\r
142 * SYNOPSIS\r
143 */\r
144 typedef struct _cl_list_obj\r
145 {\r
146         cl_list_item_t          list_item;\r
147         const void                      *p_object;              /* User's context */\r
148 \r
149 } cl_list_obj_t;\r
150 /*\r
151 * FIELDS\r
152 *       list_item\r
153 *               Used internally by the list. Users should not use this field.\r
154 *\r
155 *       p_object\r
156 *               User defined context. Users should not access this field directly.\r
157 *               Use cl_qlist_set_obj and cl_qlist_obj to set and retrieve the value\r
158 *               of this field.\r
159 *\r
160 * NOTES\r
161 *       Users can use the cl_qlist_set_obj and cl_qlist_obj functions to store\r
162 *       and retrieve context information in the list item.\r
163 *\r
164 * SEE ALSO\r
165 *       Quick List, cl_qlist_set_obj, cl_qlist_obj, cl_list_item_t\r
166 *********/\r
167 \r
168 \r
169 /****s* Component Library: Quick List/cl_qlist_t\r
170 * NAME\r
171 *       cl_qlist_t\r
172 *\r
173 * DESCRIPTION\r
174 *       Quick list structure.\r
175 *\r
176 *       The cl_qlist_t structure should be treated as opaque and should be\r
177 *       manipulated only through the provided functions.\r
178 *\r
179 * SYNOPSIS\r
180 */\r
181 typedef struct _cl_qlist\r
182 {\r
183         cl_list_item_t  end;\r
184         size_t                  count;\r
185         cl_state_t              state;\r
186 \r
187 } cl_qlist_t;\r
188 /*\r
189 * FIELDS\r
190 *       end\r
191 *               List item used to mark the end of the list.\r
192 *\r
193 *       count\r
194 *               Number of items in the list.\r
195 *\r
196 *       state\r
197 *               State of the quick list.\r
198 *\r
199 * SEE ALSO\r
200 *       Quick List\r
201 *********/\r
202 \r
203 \r
204 /****d* Component Library: Quick List/cl_pfn_qlist_apply_t\r
205 * NAME\r
206 *       cl_pfn_qlist_apply_t\r
207 *\r
208 * DESCRIPTION\r
209 *       The cl_pfn_qlist_apply_t function type defines the prototype for functions\r
210 *       used to iterate items in a quick list.\r
211 *\r
212 * SYNOPSIS\r
213 */\r
214 typedef void\r
215 (CL_API *cl_pfn_qlist_apply_t)(\r
216         IN      cl_list_item_t* const   p_list_item,\r
217         IN      void*                                   context );\r
218 /*\r
219 * PARAMETERS\r
220 *       p_list_item\r
221 *               [in] Pointer to a cl_list_item_t structure.\r
222 *\r
223 *       context\r
224 *               [in] Value passed to the callback function.\r
225 *\r
226 * RETURN VALUE\r
227 *       This function does not return a value.\r
228 *\r
229 * NOTES\r
230 *       This function type is provided as function prototype reference for the\r
231 *       function provided by users as a parameter to the cl_qlist_apply_func\r
232 *       function.\r
233 *\r
234 * SEE ALSO\r
235 *       Quick List, cl_qlist_apply_func\r
236 *********/\r
237 \r
238 \r
239 /****d* Component Library: Quick List/cl_pfn_qlist_find_t\r
240 * NAME\r
241 *       cl_pfn_qlist_find_t\r
242 *\r
243 * DESCRIPTION\r
244 *       The cl_pfn_qlist_find_t function type defines the prototype for functions\r
245 *       used to find items in a quick list.\r
246 *\r
247 * SYNOPSIS\r
248 */\r
249 typedef cl_status_t\r
250 (CL_API *cl_pfn_qlist_find_t)(\r
251         IN      const cl_list_item_t* const     p_list_item,\r
252         IN      void*                                           context );\r
253 /*\r
254 * PARAMETERS\r
255 *       p_list_item\r
256 *               [in] Pointer to a cl_list_item_t.\r
257 *\r
258 *       context\r
259 *               [in] Value passed to the callback function.\r
260 *\r
261 * RETURN VALUES\r
262 *       Return CL_SUCCESS if the desired item was found. This stops list iteration.\r
263 *\r
264 *       Return CL_NOT_FOUND to continue list iteration.\r
265 *\r
266 * NOTES\r
267 *       This function type is provided as function prototype reference for the\r
268 *       function provided by users as a parameter to the cl_qlist_find_from_head,\r
269 *       cl_qlist_find_from_tail, cl_qlist_find_next, and cl_qlist_find_prev\r
270 *       functions.\r
271 *\r
272 * SEE ALSO\r
273 *       Quick List, cl_qlist_find_from_head, cl_qlist_find_from_tail,\r
274 *       cl_qlist_find_next, cl_qlist_find_prev\r
275 *********/\r
276 \r
277 \r
278 #ifdef __cplusplus\r
279 extern "C"\r
280 {\r
281 #endif\r
282 \r
283 \r
284 /****i* Component Library: Quick List/__cl_primitive_insert\r
285 * NAME\r
286 *       __cl_primitive_insert\r
287 *\r
288 * DESCRIPTION\r
289 *       Add a new item in front of the specified item.  This is a low level\r
290 *       function for use internally by the queuing routines.\r
291 *\r
292 * SYNOPSIS\r
293 */\r
294 CL_INLINE void CL_API\r
295 __cl_primitive_insert(\r
296         IN      cl_list_item_t* const   p_list_item,\r
297         IN      cl_list_item_t* const   p_new_item )\r
298 {\r
299         /* CL_ASSERT that a non-null pointer is provided. */\r
300         CL_ASSERT( p_list_item );\r
301         /* CL_ASSERT that a non-null pointer is provided. */\r
302         CL_ASSERT( p_new_item );\r
303 \r
304         p_new_item->p_next = p_list_item;\r
305         p_new_item->p_prev = p_list_item->p_prev;\r
306         p_list_item->p_prev = p_new_item;\r
307         p_new_item->p_prev->p_next = p_new_item;\r
308 }\r
309 /*\r
310 * PARAMETERS\r
311 *       p_list_item\r
312 *               [in] Pointer to cl_list_item_t to insert in front of\r
313 *\r
314 *       p_new_item\r
315 *               [in] Pointer to cl_list_item_t to add\r
316 *\r
317 * RETURN VALUE\r
318 *       This function does not return a value.\r
319 *********/\r
320 \r
321 \r
322 /****i* Component Library: Quick List/__cl_primitive_remove\r
323 * NAME\r
324 *       __cl_primitive_remove\r
325 *\r
326 * DESCRIPTION\r
327 *       Remove an item from a list.  This is a low level routine\r
328 *       for use internally by the queuing routines.\r
329 *\r
330 * SYNOPSIS\r
331 */\r
332 CL_INLINE void CL_API\r
333 __cl_primitive_remove(\r
334         IN      cl_list_item_t* const   p_list_item )\r
335 {\r
336         /* CL_ASSERT that a non-null pointer is provided. */\r
337         CL_ASSERT( p_list_item );\r
338         CL_ASSERT( p_list_item->p_next );\r
339         CL_ASSERT( p_list_item->p_prev );\r
340 \r
341         /* set the back pointer */\r
342         p_list_item->p_next->p_prev= p_list_item->p_prev;\r
343         /* set the next pointer */\r
344         p_list_item->p_prev->p_next= p_list_item->p_next;\r
345 \r
346         /* if we're debugging, spruce up the pointers to help find bugs */\r
347 #if defined( _DEBUG_ )\r
348         if( p_list_item != p_list_item->p_next )\r
349         {\r
350                 p_list_item->p_next = NULL;\r
351                 p_list_item->p_prev = NULL;\r
352                 p_list_item->p_list = NULL;\r
353         }\r
354 #endif  /* defined( _DEBUG_ ) */\r
355 }\r
356 /*\r
357 * PARAMETERS\r
358 *       p_list_item\r
359 *               [in] Pointer to cl_list_item_t to remove\r
360 *\r
361 * RETURN VALUE\r
362 *       This function does not return a value.\r
363 *********/\r
364 \r
365 \r
366 /*\r
367  * Declaration of quick list functions\r
368  */\r
369 \r
370 /****f* Component Library: Quick List/cl_qlist_set_obj\r
371 * NAME\r
372 *       cl_qlist_set_obj\r
373 *\r
374 * DESCRIPTION\r
375 *       The cl_qlist_set_obj function sets the object stored in a list object.\r
376 *\r
377 * SYNOPSIS\r
378 */\r
379 CL_INLINE void CL_API\r
380 cl_qlist_set_obj(\r
381         IN      cl_list_obj_t* const    p_list_obj,\r
382         IN      const void* const               p_object )\r
383 {\r
384         /* CL_ASSERT that a non-null pointer is provided. */\r
385         CL_ASSERT( p_list_obj );\r
386         p_list_obj->p_object = p_object;\r
387 }\r
388 /*\r
389 * PARAMETERS\r
390 *       p_list_obj\r
391 *               [in] Pointer to a cl_list_obj_t structure.\r
392 *\r
393 *       p_object\r
394 *               [in] User defined context.\r
395 *\r
396 * RETURN VALUE\r
397 *       This function does not return a value.\r
398 *\r
399 * SEE ALSO\r
400 *       Quick List, cl_qlist_obj\r
401 *********/\r
402 \r
403 \r
404 /****f* Component Library: Quick List/cl_qlist_obj\r
405 * NAME\r
406 *       cl_qlist_obj\r
407 *\r
408 * DESCRIPTION\r
409 *       The cl_qlist_set_obj function returns the object stored in a list object.\r
410 *\r
411 * SYNOPSIS\r
412 */\r
413 CL_INLINE void* CL_API\r
414 cl_qlist_obj(\r
415         IN      const cl_list_obj_t* const      p_list_obj )\r
416 {\r
417         /* CL_ASSERT that a non-null pointer is provided. */\r
418         CL_ASSERT( p_list_obj );\r
419 \r
420         return( (void*)p_list_obj->p_object );\r
421 }\r
422 /*\r
423 * PARAMETERS\r
424 *       p_list_obj\r
425 *               [in] Pointer to a cl_list_obj_t structure.\r
426 *\r
427 * RETURN VALUE\r
428 *       Returns the value of the object pointer stored in the list object.\r
429 *\r
430 * SEE ALSO\r
431 *       Quick List, cl_qlist_set_obj\r
432 *********/\r
433 \r
434 \r
435 CL_INLINE void CL_API\r
436 __cl_qlist_reset(\r
437         IN      cl_qlist_t* const       p_list )\r
438 {\r
439         /* Point the end item to itself. */\r
440         p_list->end.p_next = &p_list->end;\r
441         p_list->end.p_prev = &p_list->end;\r
442 #if defined( _DEBUG_ )\r
443         p_list->end.p_list = p_list;\r
444 #endif\r
445 \r
446         /* Clear the count. */\r
447         p_list->count = 0;\r
448 }\r
449 \r
450 \r
451 /****f* Component Library: Quick List/cl_qlist_init\r
452 * NAME\r
453 *       cl_qlist_init\r
454 *\r
455 * DESCRIPTION\r
456 *       The cl_qlist_init function initializes a quick list.\r
457 *\r
458 * SYNOPSIS\r
459 */\r
460 CL_INLINE void CL_API\r
461 cl_qlist_init(\r
462         IN      cl_qlist_t* const       p_list )\r
463 {\r
464         /* CL_ASSERT that a non-null pointer is provided. */\r
465         CL_ASSERT( p_list );\r
466 \r
467         p_list->state = CL_INITIALIZED;\r
468 \r
469         /* Reset the quick list data structure. */\r
470         __cl_qlist_reset( p_list );\r
471 }\r
472 /*\r
473 * PARAMETERS\r
474 *       p_list\r
475 *               [in] Pointer to a cl_qlist_t structure to initialize.\r
476 *\r
477 * RETURN VALUES\r
478 *       This function does not return a value.\r
479 *\r
480 * NOTES\r
481 *       Allows calling quick list manipulation functions.\r
482 *\r
483 * SEE ALSO\r
484 *       Quick List, cl_qlist_insert_head, cl_qlist_insert_tail,\r
485 *       cl_qlist_remove_head, cl_qlist_remove_tail\r
486 *********/\r
487 \r
488 \r
489 /****f* Component Library: Quick List/cl_qlist_count\r
490 * NAME\r
491 *       cl_qlist_count\r
492 *\r
493 * DESCRIPTION\r
494 *       The cl_qlist_count function returns the number of list items stored\r
495 *       in a quick list.\r
496 *\r
497 * SYNOPSIS\r
498 */\r
499 CL_INLINE size_t CL_API\r
500 cl_qlist_count(\r
501         IN      const cl_qlist_t* const p_list )\r
502 {\r
503         /* CL_ASSERT that a non-null pointer is provided. */\r
504         CL_ASSERT( p_list );\r
505         /* CL_ASSERT that the list was initialized. */\r
506         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
507 \r
508         return( p_list->count );\r
509 }\r
510 /*\r
511 * PARAMETERS\r
512 *       p_list\r
513 *               [in] Pointer to a cl_qlist_t structure.\r
514 *\r
515 * RETURN VALUE\r
516 *       Number of items in the list.  This function iterates though the quick\r
517 *       list to count the items.\r
518 *\r
519 * SEE ALSO\r
520 *       Quick List, cl_is_qlist_empty\r
521 *********/\r
522 \r
523 \r
524 /****f* Component Library: Quick List/cl_is_qlist_empty\r
525 * NAME\r
526 *       cl_is_qlist_empty\r
527 *\r
528 * DESCRIPTION\r
529 *       The cl_is_qlist_empty function returns whether a quick list is empty.\r
530 *\r
531 * SYNOPSIS\r
532 */\r
533 CL_INLINE boolean_t CL_API\r
534 cl_is_qlist_empty(\r
535         IN      const cl_qlist_t* const p_list )\r
536 {\r
537         /* CL_ASSERT that a non-null pointer is provided. */\r
538         CL_ASSERT( p_list );\r
539         /* CL_ASSERT that the list was initialized. */\r
540         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
541 \r
542         return( !cl_qlist_count( p_list ) );\r
543 }\r
544 /*\r
545 * PARAMETERS\r
546 *       p_list\r
547 *               [in] Pointer to a cl_qlist_t structure.\r
548 *\r
549 * RETURN VALUES\r
550 *       TRUE if the specified quick list is empty.\r
551 *\r
552 *       FALSE otherwise.\r
553 *\r
554 * SEE ALSO\r
555 *       Quick List, cl_qlist_count, cl_qlist_remove_all\r
556 *********/\r
557 \r
558 \r
559 /****f* Component Library: Quick List/cl_qlist_next\r
560 * NAME\r
561 *       cl_qlist_next\r
562 *\r
563 * DESCRIPTION\r
564 *       The cl_qlist_next function returns a pointer to the list item following\r
565 *       a given list item in a quick list.\r
566 *\r
567 * SYNOPSIS\r
568 */\r
569 CL_INLINE cl_list_item_t* CL_API\r
570 cl_qlist_next(\r
571         IN      const cl_list_item_t* const     p_list_item )\r
572 {\r
573         /* CL_ASSERT that a non-null pointer is provided. */\r
574         CL_ASSERT( p_list_item );\r
575 \r
576         /* Return the next item. */\r
577         return( p_list_item->p_next );\r
578 }\r
579 /*\r
580 * PARAMETERS\r
581 *       p_list_item\r
582 *               [in] Pointer to the cl_list_item_t whose successor to return.\r
583 *\r
584 * Returns:\r
585 *       Pointer to the list item following the list item specified by\r
586 *       the p_list_item parameter in the quick list.\r
587 *\r
588 *       Pointer to the list end if p_list_item was at the tail of the list.\r
589 *\r
590 * SEE ALSO\r
591 *       Quick List, cl_qlist_head, cl_qlist_tail, cl_qlist_prev, cl_qlist_end,\r
592 *       cl_list_item_t\r
593 *********/\r
594 \r
595 \r
596 /****f* Component Library: Quick List/cl_qlist_prev\r
597 * NAME\r
598 *       cl_qlist_prev\r
599 *\r
600 * DESCRIPTION\r
601 *       The cl_qlist_prev function returns a poirter to the list item preceding\r
602 *       a given list item in a quick list.\r
603 *\r
604 * SYNOPSIS\r
605 */\r
606 CL_INLINE cl_list_item_t* CL_API\r
607 cl_qlist_prev(\r
608         IN      const cl_list_item_t* const     p_list_item )\r
609 {\r
610         /* CL_ASSERT that a non-null pointer is provided. */\r
611         CL_ASSERT( p_list_item );\r
612 \r
613         /* Return the previous item. */\r
614         return( p_list_item->p_prev );\r
615 }\r
616 /*\r
617 * PARAMETERS\r
618 *       p_list_item\r
619 *               [in] Pointer to the cl_list_item_t whose predecessor to return.\r
620 *\r
621 * Returns:\r
622 *       Pointer to the list item preceding the list item specified by\r
623 *       the p_list_item parameter in the quick list.\r
624 *\r
625 *       Pointer to the list end if p_list_item was at the tail of the list.\r
626 *\r
627 * SEE ALSO\r
628 *       Quick List, cl_qlist_head, cl_qlist_tail, cl_qlist_next, cl_qlist_end,\r
629 *       cl_list_item_t\r
630 *********/\r
631 \r
632 \r
633 /****f* Component Library: Quick List/cl_qlist_head\r
634 * NAME\r
635 *       cl_qlist_head\r
636 *\r
637 * DESCRIPTION\r
638 *       The cl_qlist_head function returns the list item at\r
639 *       the head of a quick list.\r
640 *\r
641 * SYNOPSIS\r
642 */\r
643 CL_INLINE cl_list_item_t* CL_API\r
644 cl_qlist_head(\r
645         IN      const cl_qlist_t* const p_list )\r
646 {\r
647         /* CL_ASSERT that a non-null pointer is provided. */\r
648         CL_ASSERT( p_list );\r
649         /* CL_ASSERT that the list was initialized. */\r
650         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
651 \r
652         return( cl_qlist_next( &p_list->end ) );\r
653 }\r
654 /*\r
655 * PARAMETERS\r
656 *       p_list\r
657 *               [in] Pointer to a cl_qlist_t structure.\r
658 *\r
659 * RETURN VALUES\r
660 *       Pointer to the list item at the head of the quick list.\r
661 *\r
662 *       Pointer to the list end if the list was empty.\r
663 *\r
664 * NOTES\r
665 *       cl_qlist_head does not remove the item from the list.\r
666 *\r
667 * SEE ALSO\r
668 *       Quick List, cl_qlist_tail, cl_qlist_next, cl_qlist_prev, cl_qlist_end,\r
669 *       cl_list_item_t\r
670 *********/\r
671 \r
672 \r
673 /****f* Component Library: Quick List/cl_qlist_tail\r
674 * NAME\r
675 *       cl_qlist_tail\r
676 *\r
677 * DESCRIPTION\r
678 *       The cl_qlist_tail function returns the list item at\r
679 *       the tail of a quick list.\r
680 *\r
681 * SYNOPSIS\r
682 */\r
683 CL_INLINE cl_list_item_t* CL_API\r
684 cl_qlist_tail(\r
685         IN      const cl_qlist_t* const p_list )\r
686 {\r
687         /* CL_ASSERT that a non-null pointer is provided. */\r
688         CL_ASSERT( p_list );\r
689         /* CL_ASSERT that the list was initialized. */\r
690         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
691 \r
692         return( cl_qlist_prev( &p_list->end ) );\r
693 }\r
694 /*\r
695 * PARAMETERS\r
696 *       p_list\r
697 *               [in] Pointer to a cl_qlist_t structure.\r
698 *\r
699 * RETURN VALUES\r
700 *       Pointer to the list item at the tail of the quick list.\r
701 *\r
702 *       Pointer to the list end if the list was empty.\r
703 *\r
704 * NOTES\r
705 *       cl_qlist_tail does not remove the item from the list.\r
706 *\r
707 * SEE ALSO\r
708 *       Quick List, cl_qlist_head, cl_qlist_next, cl_qlist_prev, cl_qlist_end,\r
709 *       cl_list_item_t\r
710 *********/\r
711 \r
712 \r
713 /****f* Component Library: Quick List/cl_qlist_end\r
714 * NAME\r
715 *       cl_qlist_end\r
716 *\r
717 * DESCRIPTION\r
718 *       The cl_qlist_end function returns the end of a quick list.\r
719 *\r
720 * SYNOPSIS\r
721 */\r
722 CL_INLINE const cl_list_item_t* const CL_API\r
723 cl_qlist_end(\r
724         IN      const cl_qlist_t* const p_list )\r
725 {\r
726         /* CL_ASSERT that a non-null pointer is provided. */\r
727         CL_ASSERT( p_list );\r
728         /* CL_ASSERT that the list was initialized. */\r
729         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
730 \r
731         return( &p_list->end );\r
732 }\r
733 /*\r
734 * PARAMETERS\r
735 *       p_list\r
736 *               [in] Pointer to a cl_qlist_t structure.\r
737 *\r
738 * RETURN VALUE\r
739 *       Pointer to the end of the list.\r
740 *\r
741 * NOTES\r
742 *       cl_qlist_end is useful for determining the validity of list items returned\r
743 *       by cl_qlist_head, cl_qlist_tail, cl_qlist_next, cl_qlist_prev, as well as\r
744 *       the cl_qlist_find functions.  If the list item pointer returned by any of\r
745 *       these functions compares to the end, the end of the list was encoutered.\r
746 *       When using cl_qlist_head or cl_qlist_tail, this condition indicates that\r
747 *       the list is empty.\r
748 *\r
749 * SEE ALSO\r
750 *       Quick List, cl_qlist_head, cl_qlist_tail, cl_qlist_next, cl_qlist_prev,\r
751 *       cl_list_item_t\r
752 *********/\r
753 \r
754 \r
755 /****f* Component Library: Quick List/cl_qlist_insert_head\r
756 * NAME\r
757 *       cl_qlist_insert_head\r
758 *\r
759 * DESCRIPTION\r
760 *       The cl_qlist_insert_head function inserts a list item at the\r
761 *       head of a quick list.\r
762 *\r
763 * SYNOPSIS\r
764 */\r
765 CL_INLINE void CL_API\r
766 cl_qlist_insert_head(\r
767         IN      cl_qlist_t* const               p_list,\r
768         IN      cl_list_item_t* const   p_list_item )\r
769 {\r
770         /* CL_ASSERT that a non-null pointer is provided. */\r
771         CL_ASSERT( p_list );\r
772         /* CL_ASSERT that a non-null pointer is provided. */\r
773         CL_ASSERT( p_list_item );\r
774         /* CL_ASSERT that the list was initialized. */\r
775         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
776 \r
777         /*\r
778          * The list item must not already be part of the list.  Note that this\r
779          * assertion may fail if an uninitialized list item happens to have its\r
780          * list pointer equal to the specified list.  The chances of this\r
781          * happening are acceptable in light of the value of this check.\r
782          */\r
783         CL_ASSERT( p_list_item->p_list != p_list );\r
784 \r
785 #if defined( _DEBUG_ )\r
786         p_list_item->p_list = p_list;\r
787 #endif\r
788 \r
789         /* Insert before the head. */\r
790         __cl_primitive_insert( cl_qlist_head( p_list ), p_list_item );\r
791 \r
792         p_list->count++;\r
793 }\r
794 /*\r
795 * PARAMETERS\r
796 *       p_list\r
797 *               [in] Pointer to a cl_qlist_t structure into which to insert the object.\r
798 *\r
799 *       p_list_item\r
800 *               [in] Pointer to a cl_list_item_t structure to add.\r
801 *\r
802 * RETURN VALUE\r
803 *       This function does not return a value.\r
804 *\r
805 * NOTES\r
806 *       In debug builds, cl_qlist_insert_head asserts that the specified list item\r
807 *       is not already in the list.\r
808 *\r
809 * SEE ALSO\r
810 *       Quick List, cl_qlist_insert_tail, cl_qlist_insert_list_head,\r
811 *       cl_qlist_insert_list_tail, cl_qlist_insert_array_head,\r
812 *       cl_qlist_insert_array_tail, cl_qlist_insert_prev, cl_qlist_insert_next,\r
813 *       cl_qlist_remove_head, cl_list_item_t\r
814 *********/\r
815 \r
816 \r
817 /****f* Component Library: Quick List/cl_qlist_insert_tail\r
818 * NAME\r
819 *       cl_qlist_insert_tail\r
820 *\r
821 * DESCRIPTION\r
822 *       The cl_qlist_insert_tail function inserts a list item at the tail\r
823 *       of a quick list.\r
824 *\r
825 * SYNOPSIS\r
826 */\r
827 CL_INLINE void CL_API\r
828 cl_qlist_insert_tail(\r
829         IN      cl_qlist_t* const               p_list,\r
830         IN      cl_list_item_t* const   p_list_item )\r
831 {\r
832         /* CL_ASSERT that a non-null pointer is provided. */\r
833         CL_ASSERT( p_list );\r
834         /* CL_ASSERT that a non-null pointer is provided. */\r
835         CL_ASSERT( p_list_item );\r
836         /* CL_ASSERT that the list was initialized. */\r
837         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
838 \r
839         /*\r
840          * The list item must not already be part of the list.  Note that this\r
841          * assertion may fail if an uninitialized list item happens to have its\r
842          * list pointer equal to the specified list.  The chances of this\r
843          * happening are acceptable in light of the value of this check.\r
844          */\r
845         CL_ASSERT( p_list_item->p_list != p_list );\r
846 \r
847 #if defined( _DEBUG_ )\r
848         p_list_item->p_list = p_list;\r
849 #endif\r
850 \r
851         /*\r
852          * Put the new element in front of the end which is the same\r
853          * as being at the tail\r
854          */\r
855         __cl_primitive_insert( &p_list->end, p_list_item );\r
856 \r
857         p_list->count++;\r
858 }\r
859 /*\r
860 * PARAMETERS\r
861 *       p_list\r
862 *               [in] Pointer to a cl_qlist_t structure into which to insert the object.\r
863 *\r
864 *       p_list_item\r
865 *               [in] Pointer to cl_list_item_t structure to add.\r
866 *\r
867 * RETURN VALUE\r
868 *       This function does not return a value.\r
869 *\r
870 * NOTES\r
871 *       In debug builds, cl_qlist_insert_tail asserts that the specified list item\r
872 *       is not already in the list.\r
873 *\r
874 * SEE ALSO\r
875 *       Quick List, cl_qlist_insert_head, cl_qlist_insert_list_head,\r
876 *       cl_qlist_insert_list_tail, cl_qlist_insert_array_head,\r
877 *       cl_qlist_insert_array_tail, cl_qlist_insert_prev, cl_qlist_insert_next,\r
878 *       cl_qlist_remove_tail, cl_list_item_t\r
879 *********/\r
880 \r
881 \r
882 /****f* Component Library: Quick List/cl_qlist_insert_list_head\r
883 * NAME\r
884 *       cl_qlist_insert_list_head\r
885 *\r
886 * DESCRIPTION\r
887 *       The cl_qlist_insert_list_head function merges two quick lists by\r
888 *       inserting one at the head of the other.\r
889 *\r
890 * SYNOPSIS\r
891 */\r
892 CL_EXPORT void CL_API\r
893 cl_qlist_insert_list_head(\r
894         IN      cl_qlist_t* const       p_dest_list,\r
895         IN      cl_qlist_t* const       p_src_list );\r
896 /*\r
897 * PARAMETERS\r
898 *       p_dest_list\r
899 *               [in] Pointer to destination quicklist object.\r
900 *\r
901 *       p_src_list\r
902 *               [in] Pointer to quicklist to add.\r
903 *\r
904 * RETURN VALUE\r
905 *       This function does not return a value.\r
906 *\r
907 * NOTES\r
908 *       Inserts all list items in the source list to the head of the\r
909 *       destination list. The ordering of the list items is preserved.\r
910 *\r
911 *       The list pointed to by the p_src_list parameter is empty when\r
912 *       the call returns.\r
913 *\r
914 * SEE ALSO\r
915 *       Quick List, cl_qlist_insert_list_tail, cl_qlist_insert_head,\r
916 *       cl_qlist_insert_tail, cl_qlist_insert_array_head,\r
917 *       cl_qlist_insert_array_tail, cl_qlist_insert_prev, cl_qlist_insert_next,\r
918 *       cl_list_item_t\r
919 *********/\r
920 \r
921 \r
922 /****f* Component Library: Quick List/cl_qlist_insert_list_tail\r
923 * NAME\r
924 *       cl_qlist_insert_list_tail\r
925 *\r
926 * DESCRIPTION\r
927 *       The cl_qlist_insert_list_tail function merges two quick lists by\r
928 *       inserting one at the tail of the other.\r
929 *\r
930 * SYNOPSIS\r
931 */\r
932 CL_EXPORT void CL_API\r
933 cl_qlist_insert_list_tail(\r
934         IN      cl_qlist_t* const       p_dest_list,\r
935         IN      cl_qlist_t* const       p_src_list );\r
936 /*\r
937 * PARAMETERS\r
938 *       p_dest_list\r
939 *               [in] Pointer to destination quicklist object\r
940 *\r
941 *       p_src_list\r
942 *               [in] Pointer to quicklist to add\r
943 *\r
944 * RETURN VALUE\r
945 *       This function does not return a value.\r
946 *\r
947 * NOTES\r
948 *       Inserts all list items in the source list to the tail of the\r
949 *       destination list. The ordering of the list items is preserved.\r
950 *\r
951 *       The list pointed to by the p_src_list parameter is empty when\r
952 *       the call returns.\r
953 *\r
954 * SEE ALSO\r
955 *       Quick List, cl_qlist_insert_list_head, cl_qlist_insert_head,\r
956 *       cl_qlist_insert_tail, cl_qlist_insert_array_head,\r
957 *       cl_qlist_insert_array_tail, cl_qlist_insert_prev, cl_qlist_insert_next,\r
958 *       cl_list_item_t\r
959 *********/\r
960 \r
961 \r
962 /****f* Component Library: Quick List/cl_qlist_insert_array_head\r
963 * NAME\r
964 *       cl_qlist_insert_array_head\r
965 *\r
966 * DESCRIPTION\r
967 *       The cl_qlist_insert_array_head function inserts an array of list items\r
968 *       at the head of a quick list.\r
969 *\r
970 * SYNOPSIS\r
971 */\r
972 CL_EXPORT void CL_API\r
973 cl_qlist_insert_array_head(\r
974         IN      cl_qlist_t* const               p_list,\r
975         IN      cl_list_item_t* const   p_array,\r
976         IN      size_t                                  item_count,\r
977         IN      const size_t                    item_size );\r
978 /*\r
979 * PARAMETERS\r
980 *       p_list\r
981 *               [in] Pointer to a cl_qlist_t structure into which to insert\r
982 *               the objects.\r
983 *\r
984 *       p_array\r
985 *               [in] Pointer to the first list item in an array of cl_list_item_t\r
986 *               structures.\r
987 *\r
988 *       item_count\r
989 *               [in] Number of cl_list_item_t structures in the array.\r
990 *\r
991 *       item_size\r
992 *               [in] Size of the items added to the list. This is the stride in the\r
993 *               array from one cl_list_item_t structure to the next.\r
994 *\r
995 * RETURN VALUE\r
996 *       This function does not return a value.\r
997 *\r
998 * NOTES\r
999 *       Inserts all the list items in the array specified by the p_array parameter\r
1000 *       to the head of the quick list specified by the p_list parameter,\r
1001 *       preserving ordering of the list items.\r
1002 *\r
1003 *       The array pointer passed into the function points to the cl_list_item_t\r
1004 *       in the first element of the caller's element array.  There is no\r
1005 *       restriction on where the element is stored in the parent structure.\r
1006 *\r
1007 * SEE ALSO\r
1008 *       Quick List, cl_qlist_insert_array_tail, cl_qlist_insert_head,\r
1009 *       cl_qlist_insert_tail, cl_qlist_insert_list_head, cl_qlist_insert_list_tail,\r
1010 *       cl_qlist_insert_prev, cl_qlist_insert_next, cl_list_item_t\r
1011 *********/\r
1012 \r
1013 \r
1014 /****f* Component Library: Quick List/cl_qlist_insert_array_tail\r
1015 * NAME\r
1016 *       cl_qlist_insert_array_tail\r
1017 *\r
1018 * DESCRIPTION\r
1019 *       The cl_qlist_insert_array_tail function inserts an array of list items\r
1020 *       at the tail of a quick list.\r
1021 *\r
1022 * SYNOPSIS\r
1023 */\r
1024 CL_EXPORT void CL_API\r
1025 cl_qlist_insert_array_tail(\r
1026         IN      cl_qlist_t* const               p_list,\r
1027         IN      cl_list_item_t* const   p_array,\r
1028         IN      size_t                                  item_count,\r
1029         IN      const size_t                    item_size);\r
1030 /*\r
1031 * PARAMETERS\r
1032 *       p_list\r
1033 *               [in] Pointer to a cl_qlist_t structure into which to insert\r
1034 *               the objects.\r
1035 *\r
1036 *       p_array\r
1037 *               [in] Pointer to the first list item in an array of cl_list_item_t\r
1038 *               structures.\r
1039 *\r
1040 *       item_count\r
1041 *               [in] Number of cl_list_item_t structures in the array.\r
1042 *\r
1043 *       item_size\r
1044 *               [in] Size of the items added to the list. This is the stride in the\r
1045 *               array from one cl_list_item_t structure to the next.\r
1046 *\r
1047 * RETURN VALUE\r
1048 *       This function does not return a value.\r
1049 *\r
1050 * NOTES\r
1051 *       Inserts all the list items in the array specified by the p_array parameter\r
1052 *       to the tail of the quick list specified by the p_list parameter,\r
1053 *       preserving ordering of the list items.\r
1054 *\r
1055 *       The array pointer passed into the function points to the cl_list_item_t\r
1056 *       in the first element of the caller's element array.  There is no\r
1057 *       restriction on where the element is stored in the parent structure.\r
1058 *\r
1059 * SEE ALSO\r
1060 *       Quick List, cl_qlist_insert_array_head, cl_qlist_insert_head,\r
1061 *       cl_qlist_insert_tail, cl_qlist_insert_list_head, cl_qlist_insert_list_tail,\r
1062 *       cl_qlist_insert_prev, cl_qlist_insert_next, cl_list_item_t\r
1063 *********/\r
1064 \r
1065 \r
1066 /****f* Component Library: Quick List/cl_qlist_insert_prev\r
1067 * NAME\r
1068 *       cl_qlist_insert_prev\r
1069 *\r
1070 * DESCRIPTION\r
1071 *       The cl_qlist_insert_prev function inserts a list item before a\r
1072 *       specified list item in a quick list.\r
1073 *\r
1074 * SYNOPSIS\r
1075 */\r
1076 CL_INLINE void CL_API\r
1077 cl_qlist_insert_prev(\r
1078         IN      cl_qlist_t* const               p_list,\r
1079         IN      cl_list_item_t* const   p_list_item,\r
1080         IN      cl_list_item_t* const   p_new_item )\r
1081 {\r
1082         /* CL_ASSERT that a non-null pointer is provided. */\r
1083         CL_ASSERT( p_list );\r
1084         /* CL_ASSERT that a non-null pointer is provided. */\r
1085         CL_ASSERT( p_list_item );\r
1086         /* CL_ASSERT that a non-null pointer is provided. */\r
1087         CL_ASSERT( p_new_item );\r
1088         /* CL_ASSERT that the list was initialized. */\r
1089         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
1090 \r
1091         /*\r
1092          * The list item must not already be part of the list.  Note that this\r
1093          * assertion may fail if an uninitialized list item happens to have its\r
1094          * list pointer equal to the specified list.  The chances of this\r
1095          * happening are acceptable in light of the value of this check.\r
1096          */\r
1097         CL_ASSERT( p_new_item->p_list != p_list );\r
1098 \r
1099 #if defined( _DEBUG_ )\r
1100         p_new_item->p_list = p_list;\r
1101 #endif\r
1102 \r
1103         __cl_primitive_insert( p_list_item, p_new_item );\r
1104 \r
1105         p_list->count++;\r
1106 }\r
1107 /*\r
1108 * PARAMETERS\r
1109 *       p_list\r
1110 *               [in] Pointer to a cl_qlist_t structure into which to add the new item.\r
1111 *\r
1112 *       p_list_item\r
1113 *               [in] Pointer to a cl_list_item_t structure.\r
1114 *\r
1115 *       p_new_item\r
1116 *               [in] Pointer to a cl_list_item_t structure to add to the quick list.\r
1117 *\r
1118 * RETURN VALUE\r
1119 *       This function does not return a value.\r
1120 *\r
1121 * NOTES\r
1122 *       Inserts the new list item before the list item specified by p_list_item.\r
1123 *\r
1124 * SEE ALSO\r
1125 *       Quick List, cl_qlist_insert_next, cl_qlist_insert_head,\r
1126 *       cl_qlist_insert_tail, cl_qlist_insert_list_head, cl_qlist_insert_list_tail,\r
1127 *       cl_qlist_insert_array_head, cl_qlist_insert_array_tail, cl_list_item_t\r
1128 *********/\r
1129 \r
1130 \r
1131 /****f* Component Library: Quick List/cl_qlist_insert_next\r
1132 * NAME\r
1133 *       cl_qlist_insert_next\r
1134 *\r
1135 * DESCRIPTION\r
1136 *       The cl_qlist_insert_next function inserts a list item after a specified\r
1137 *       list item in a quick list.\r
1138 *\r
1139 * SYNOPSIS\r
1140 */\r
1141 CL_INLINE void CL_API\r
1142 cl_qlist_insert_next(\r
1143         IN      cl_qlist_t* const               p_list,\r
1144         IN      cl_list_item_t* const   p_list_item,\r
1145         IN      cl_list_item_t* const   p_new_item )\r
1146 {\r
1147         /* CL_ASSERT that a non-null pointer is provided. */\r
1148         CL_ASSERT( p_list );\r
1149         /* CL_ASSERT that a non-null pointer is provided. */\r
1150         CL_ASSERT( p_list_item );\r
1151         /* CL_ASSERT that a non-null pointer is provided. */\r
1152         CL_ASSERT( p_new_item );\r
1153         /* CL_ASSERT that the list was initialized. */\r
1154         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
1155 \r
1156         /*\r
1157          * The list item must not already be part of the list.  Note that this\r
1158          * assertion may fail if an uninitialized list item happens to have its\r
1159          * list pointer equal to the specified list.  The chances of this\r
1160          * happening are acceptable in light of the value of this check.\r
1161          */\r
1162         CL_ASSERT( p_new_item->p_list != p_list );\r
1163 \r
1164 #if defined( _DEBUG_ )\r
1165         p_new_item->p_list = p_list;\r
1166 #endif\r
1167 \r
1168         __cl_primitive_insert( cl_qlist_next( p_list_item ), p_new_item );\r
1169 \r
1170         p_list->count++;\r
1171 }\r
1172 /*\r
1173 * PARAMETERS\r
1174 *       p_list\r
1175 *               [in] Pointer to a cl_qlist_t structure into which to add the new item.\r
1176 *\r
1177 *       p_list_item\r
1178 *               [in] Pointer to a cl_list_item_t structure.\r
1179 *\r
1180 *       p_new_item\r
1181 *               [in] Pointer to a cl_list_item_t structure to add to the quick list.\r
1182 *\r
1183 * RETURN VALUE\r
1184 *       This function does not return a value.\r
1185 *\r
1186 * NOTES\r
1187 *       Inserts the new list item after the list item specified by p_list_item.\r
1188 *       The list item specified by p_list_item must be in the quick list.\r
1189 *\r
1190 * SEE ALSO\r
1191 *       Quick List, cl_qlist_insert_prev, cl_qlist_insert_head,\r
1192 *       cl_qlist_insert_tail, cl_qlist_insert_list_head, cl_qlist_insert_list_tail,\r
1193 *       cl_qlist_insert_array_head, cl_qlist_insert_array_tail, cl_list_item_t\r
1194 *********/\r
1195 \r
1196 \r
1197 /****f* Component Library: Quick List/cl_qlist_remove_head\r
1198 * NAME\r
1199 *       cl_qlist_remove_head\r
1200 *\r
1201 * DESCRIPTION\r
1202 *       The cl_qlist_remove_head function removes and returns the list item\r
1203 *       at the head of a quick list.\r
1204 *\r
1205 * SYNOPSIS\r
1206 */\r
1207 CL_INLINE cl_list_item_t* CL_API\r
1208 cl_qlist_remove_head(\r
1209         IN      cl_qlist_t* const       p_list )\r
1210 {\r
1211         cl_list_item_t  *p_item;\r
1212 \r
1213         /* CL_ASSERT that a non-null pointer is provided. */\r
1214         CL_ASSERT( p_list );\r
1215         /* CL_ASSERT that the list was initialized. */\r
1216         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
1217 \r
1218         p_item = cl_qlist_head( p_list );\r
1219         /* CL_ASSERT that the list item is part of the list. */\r
1220         CL_ASSERT( p_item->p_list == p_list );\r
1221 \r
1222         if( p_item == cl_qlist_end( p_list ) )\r
1223                 return( p_item );\r
1224 \r
1225         __cl_primitive_remove( p_item );\r
1226 \r
1227         p_list->count--;\r
1228 \r
1229         return( p_item );\r
1230 }\r
1231 /*\r
1232 * PARAMETERS\r
1233 *       p_list\r
1234 *               [in] Pointer to a cl_qlist_t structure.\r
1235 *\r
1236 * RETURN VALUES\r
1237 *       Returns a pointer to the list item formerly at the head of the quick list.\r
1238 *\r
1239 *       Pointer to the list end if the list was empty.\r
1240 *\r
1241 * SEE ALSO\r
1242 *       Quick List, cl_qlist_remove_tail, cl_qlist_remove_all, cl_qlist_remove_item,\r
1243 *       cl_qlist_end, cl_qlist_head, cl_list_item_t\r
1244 *********/\r
1245 \r
1246 \r
1247 /****f* Component Library: Quick List/cl_qlist_remove_tail\r
1248 * NAME\r
1249 *       cl_qlist_remove_tail\r
1250 *\r
1251 * DESCRIPTION\r
1252 *       The cl_qlist_remove_tail function removes and returns the list item\r
1253 *       at the tail of a quick list.\r
1254 *\r
1255 * SYNOPSIS\r
1256 */\r
1257 CL_INLINE cl_list_item_t* CL_API\r
1258 cl_qlist_remove_tail(\r
1259         IN      cl_qlist_t* const       p_list )\r
1260 {\r
1261         cl_list_item_t  *p_item;\r
1262 \r
1263         /* CL_ASSERT that a non-null pointer is provided. */\r
1264         CL_ASSERT( p_list );\r
1265         /* CL_ASSERT that the list was initialized. */\r
1266         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
1267 \r
1268         p_item = cl_qlist_tail( p_list );\r
1269         /* CL_ASSERT that the list item is part of the list. */\r
1270         CL_ASSERT( p_item->p_list == p_list );\r
1271 \r
1272         if( p_item == cl_qlist_end( p_list ) )\r
1273                 return( p_item );\r
1274 \r
1275         __cl_primitive_remove( p_item );\r
1276 \r
1277         p_list->count--;\r
1278 \r
1279         return( p_item );\r
1280 }\r
1281 /*\r
1282 * PARAMETERS\r
1283 *       p_list\r
1284 *               [in] Pointer to a cl_qlist_t structure.\r
1285 *\r
1286 * RETURN VALUES\r
1287 *       Returns a pointer to the list item formerly at the tail of the quick list.\r
1288 *\r
1289 *       Pointer to the list end if the list was empty.\r
1290 *\r
1291 * SEE ALSO\r
1292 *       Quick List, cl_qlist_remove_head, cl_qlist_remove_all, cl_qlist_remove_item,\r
1293 *       cl_qlist_end, cl_qlist_tail, cl_list_item_t\r
1294 *********/\r
1295 \r
1296 \r
1297 /****f* Component Library: Quick List/cl_qlist_remove_item\r
1298 * NAME\r
1299 *       cl_qlist_remove_item\r
1300 *\r
1301 * DESCRIPTION\r
1302 *       The cl_qlist_remove_item function removes a specific list item from a quick list.\r
1303 *\r
1304 * SYNOPSIS\r
1305 */\r
1306 CL_INLINE void CL_API\r
1307 cl_qlist_remove_item(\r
1308         IN      cl_qlist_t* const               p_list,\r
1309         IN      cl_list_item_t* const   p_list_item )\r
1310 {\r
1311         /* CL_ASSERT that a non-null pointer is provided. */\r
1312         CL_ASSERT( p_list );\r
1313         /* CL_ASSERT that a non-null pointer is provided. */\r
1314         CL_ASSERT( p_list_item  );\r
1315         /* CL_ASSERT that the list was initialized. */\r
1316         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
1317         /* CL_ASSERT that the list item is part of the list. */\r
1318         CL_ASSERT( p_list_item->p_list == p_list );\r
1319 \r
1320         if( p_list_item == cl_qlist_end( p_list ) )\r
1321                 return;\r
1322 \r
1323         __cl_primitive_remove( p_list_item );\r
1324 \r
1325         p_list->count--;\r
1326 }\r
1327 /*\r
1328 * PARAMETERS\r
1329 *       p_list\r
1330 *               [in] Pointer to a cl_qlist_t structure from which to remove the item.\r
1331 *\r
1332 *       p_list_item\r
1333 *               [in] Pointer to a cl_list_item_t structure to remove.\r
1334 *\r
1335 * RETURN VALUE\r
1336 *       This function does not return a value.\r
1337 *\r
1338 * NOTES\r
1339 *       Removes the list item pointed to by the p_list_item parameter from\r
1340 *       its list.\r
1341 *\r
1342 * SEE ALSO\r
1343 *       Quick List, cl_qlist_remove_head, cl_qlist_remove_tail, cl_qlist_remove_all,\r
1344 *       cl_list_item_t\r
1345 *********/\r
1346 \r
1347 \r
1348 /****f* Component Library: Quick List/cl_qlist_remove_all\r
1349 * NAME\r
1350 *       cl_qlist_remove_all\r
1351 *\r
1352 * DESCRIPTION\r
1353 *       The cl_qlist_remove_all function removes all items from a quick list.\r
1354 *\r
1355 * SYNOPSIS\r
1356 */\r
1357 CL_INLINE void CL_API\r
1358 cl_qlist_remove_all(\r
1359         IN      cl_qlist_t* const       p_list )\r
1360 {\r
1361 #if defined( _DEBUG_ )\r
1362         cl_list_item_t  *p_list_item;\r
1363 \r
1364         /* CL_ASSERT that a non-null pointer is provided. */\r
1365         CL_ASSERT( p_list );\r
1366         /* CL_ASSERT that the list was initialized. */\r
1367         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
1368         p_list_item = cl_qlist_head( p_list );\r
1369         while( p_list_item != cl_qlist_end( p_list ) )\r
1370         {\r
1371                 p_list_item = cl_qlist_next( p_list_item );\r
1372                 cl_qlist_prev( p_list_item )->p_list = NULL;\r
1373         }\r
1374 #endif\r
1375 \r
1376         __cl_qlist_reset( p_list );\r
1377 }\r
1378 /*\r
1379 * PARAMETERS\r
1380 *       p_list\r
1381 *               [in] Pointer to a cl_qlist_t structure.\r
1382 *\r
1383 * RETURN VALUE\r
1384 *       This function does not return a value.\r
1385 *\r
1386 * SEE ALSO\r
1387 *       Quick List, cl_qlist_remove_head, cl_qlist_remove_tail,\r
1388 *       cl_qlist_remove_item, cl_list_item_t\r
1389 *********/\r
1390 \r
1391 \r
1392 /****f* Component Library: Quick List/cl_is_item_in_qlist\r
1393 * NAME\r
1394 *       cl_is_item_in_qlist\r
1395 *\r
1396 * DESCRIPTION\r
1397 *       The cl_is_item_in_qlist function checks for the presence of a\r
1398 *       list item in a quick list.\r
1399 *\r
1400 * SYNOPSIS\r
1401 */\r
1402 CL_EXPORT boolean_t CL_API\r
1403 cl_is_item_in_qlist(\r
1404         IN      const cl_qlist_t* const         p_list,\r
1405         IN      const cl_list_item_t* const     p_list_item );\r
1406 /*\r
1407 * PARAMETERS\r
1408 *       p_list\r
1409 *               [in] Pointer to a cl_qlist_t structure.\r
1410 *\r
1411 *       p_list_item\r
1412 *               [in] Pointer to the cl_list_item_t to find.\r
1413 *\r
1414 * RETURN VALUES\r
1415 *       TRUE if the list item was found in the quick list.\r
1416 *\r
1417 *       FALSE otherwise.\r
1418 *\r
1419 * SEE ALSO\r
1420 *       Quick List, cl_qlist_remove_item, cl_list_item_t\r
1421 *********/\r
1422 \r
1423 \r
1424 /****f* Component Library: Quick List/cl_qlist_find_next\r
1425 * NAME\r
1426 *       cl_qlist_find_next\r
1427 *\r
1428 * DESCRIPTION\r
1429 *       The cl_qlist_find_next function invokes a specified function to\r
1430 *       search for an item, starting from a given list item.\r
1431 *\r
1432 * SYNOPSIS\r
1433 */\r
1434 CL_EXPORT cl_list_item_t* CL_API\r
1435 cl_qlist_find_next(\r
1436         IN      const cl_qlist_t* const         p_list,\r
1437         IN      const cl_list_item_t* const     p_list_item,\r
1438         IN      cl_pfn_qlist_find_t                     pfn_func,\r
1439         IN      const void* const                       context );\r
1440 /*\r
1441 * PARAMETERS\r
1442 *       p_list\r
1443 *               [in] Pointer to a cl_qlist_t structure in which to search.\r
1444 *\r
1445 *       p_list_item\r
1446 *               [in] Pointer to a cl_list_item_t structure from which to start the search.\r
1447 *\r
1448 *       pfn_func\r
1449 *               [in] Function invoked to determine if a match was found.\r
1450 *               See the cl_pfn_qlist_find_t function type declaration for details\r
1451 *               about the callback function.\r
1452 *\r
1453 *       context\r
1454 *               [in] Value to pass to the callback functions to provide context if a\r
1455 *               callback function is provided, or value compared to the quick list's\r
1456 *               list items.\r
1457 *\r
1458 * Returns:\r
1459 *       Pointer to the list item, if found.\r
1460 *\r
1461 *       p_list_item if not found.\r
1462 *\r
1463 * NOTES\r
1464 *       cl_qlist_find_next does not remove list items from the list.\r
1465 *       The list item is returned when the function specified by the pfn_func\r
1466 *       parameter returns CL_SUCCESS.  The list item from which the search starts is\r
1467 *       excluded from the search.\r
1468 *\r
1469 *       The function provided by the pfn_func must not perform any list operations,\r
1470 *       as these would corrupt the list.\r
1471 *\r
1472 * SEE ALSO\r
1473 *       Quick List, cl_qlist_find_prev, cl_qlist_find_from_head,\r
1474 *       cl_qlist_find_from_tail, cl_qlist_end, cl_qlist_apply_func,\r
1475 *       cl_qlist_move_items, cl_list_item_t, cl_pfn_qlist_find_t\r
1476 *********/\r
1477 \r
1478 \r
1479 /****f* Component Library: Quick List/cl_qlist_find_prev\r
1480 * NAME\r
1481 *       cl_qlist_find_prev\r
1482 *\r
1483 * DESCRIPTION\r
1484 *       The cl_qlist_find_prev function invokes a specified function to\r
1485 *       search backward for an item, starting from a given list item.\r
1486 *\r
1487 * SYNOPSIS\r
1488 */\r
1489 CL_EXPORT cl_list_item_t* CL_API\r
1490 cl_qlist_find_prev(\r
1491         IN      const cl_qlist_t* const         p_list,\r
1492         IN      const cl_list_item_t* const     p_list_item,\r
1493         IN      cl_pfn_qlist_find_t                     pfn_func,\r
1494         IN      const void* const                       context );\r
1495 /*\r
1496 * PARAMETERS\r
1497 *       p_list\r
1498 *               [in] Pointer to a cl_qlist_t structure in which to search.\r
1499 *\r
1500 *       p_list_item\r
1501 *               [in] Pointer to a cl_list_item_t structure from which to start the search.\r
1502 *\r
1503 *       pfn_func\r
1504 *               [in] Function invoked to determine if a match was found.\r
1505 *               See the cl_pfn_qlist_find_t function type declaration for details\r
1506 *               about the callback function.\r
1507 *\r
1508 *       context\r
1509 *               [in] Value to pass to the callback functions to provide context if a\r
1510 *               callback function is provided, or value compared to the quick list's\r
1511 *               list items.\r
1512 *\r
1513 * Returns:\r
1514 *       Pointer to the list item, if found.\r
1515 *\r
1516 *       p_list_item if not found.\r
1517 *\r
1518 * NOTES\r
1519 *       cl_qlist_find_prev does not remove list items from the list.\r
1520 *       The list item is returned when the function specified by the pfn_func\r
1521 *       parameter returns CL_SUCCESS.  The list item from which the search starts is\r
1522 *       excluded from the search.\r
1523 *\r
1524 *       The function provided by the pfn_func must not perform any list operations,\r
1525 *       as these would corrupt the list.\r
1526 *\r
1527 * SEE ALSO\r
1528 *       Quick List, cl_qlist_find_next, cl_qlist_find_from_head,\r
1529 *       cl_qlist_find_from_tail, cl_qlist_end, cl_qlist_apply_func,\r
1530 *       cl_qlist_move_items, cl_list_item_t, cl_pfn_qlist_find_t\r
1531 *********/\r
1532 \r
1533 \r
1534 /****f* Component Library: Quick List/cl_qlist_find_from_head\r
1535 * NAME\r
1536 *       cl_qlist_find_from_head\r
1537 *\r
1538 * DESCRIPTION\r
1539 *       The cl_qlist_find_from_head function invokes a specified function to\r
1540 *       search for an item, starting at the head of a quick list.\r
1541 *\r
1542 * SYNOPSIS\r
1543 */\r
1544 CL_INLINE cl_list_item_t* CL_API\r
1545 cl_qlist_find_from_head(\r
1546         IN      const cl_qlist_t* const p_list,\r
1547         IN      cl_pfn_qlist_find_t             pfn_func,\r
1548         IN      const void* const               context )\r
1549 {\r
1550         /* CL_ASSERT that a non-null pointer is provided. */\r
1551         CL_ASSERT( p_list );\r
1552         /* CL_ASSERT that the list was initialized. */\r
1553         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
1554         /* CL_ASSERT that a find function is provided. */\r
1555         CL_ASSERT( pfn_func );\r
1556 \r
1557         return( cl_qlist_find_next( p_list, cl_qlist_end( p_list ), pfn_func,\r
1558                 context ) );\r
1559 }\r
1560 /*\r
1561 * PARAMETERS\r
1562 *       p_list\r
1563 *               [in] Pointer to a cl_qlist_t structure.\r
1564 *\r
1565 *       pfn_func\r
1566 *               [in] Function invoked to determine if a match was found.\r
1567 *               See the cl_pfn_qlist_find_t function type declaration for details\r
1568 *               about the callback function.\r
1569 *\r
1570 *       context\r
1571 *               [in] Value to pass to the callback functions to provide context if a\r
1572 *               callback function is provided, or value compared to the quick list's\r
1573 *               list items.\r
1574 *\r
1575 * Returns:\r
1576 *       Pointer to the list item, if found.\r
1577 *\r
1578 *       Pointer to the list end otherwise\r
1579 *\r
1580 * NOTES\r
1581 *       cl_qlist_find_from_head does not remove list items from the list.\r
1582 *       The list item is returned when the function specified by the pfn_func\r
1583 *       parameter returns CL_SUCCESS.\r
1584 *\r
1585 *       The function provided by the pfn_func parameter must not perform any list\r
1586 *       operations, as these would corrupt the list.\r
1587 *\r
1588 * SEE ALSO\r
1589 *       Quick List, cl_qlist_find_from_tail, cl_qlist_find_next, cl_qlist_find_prev,\r
1590 *       cl_qlist_end, cl_qlist_apply_func, cl_qlist_move_items, cl_list_item_t,\r
1591 *       cl_pfn_qlist_find_t\r
1592 *********/\r
1593 \r
1594 \r
1595 /****f* Component Library: Quick List/cl_qlist_find_from_tail\r
1596 * NAME\r
1597 *       cl_qlist_find_from_tail\r
1598 *\r
1599 * DESCRIPTION\r
1600 *       The cl_qlist_find_from_tail function invokes a specified function to\r
1601 *       search for an item, starting at the tail of a quick list.\r
1602 *\r
1603 * SYNOPSIS\r
1604 */\r
1605 CL_INLINE cl_list_item_t* CL_API\r
1606 cl_qlist_find_from_tail(\r
1607         IN      const cl_qlist_t* const p_list,\r
1608         IN      cl_pfn_qlist_find_t             pfn_func,\r
1609         IN      const void* const               context )\r
1610 {\r
1611         /* CL_ASSERT that a non-null pointer is provided. */\r
1612         CL_ASSERT( p_list );\r
1613         /* CL_ASSERT that the list was initialized. */\r
1614         CL_ASSERT( p_list->state == CL_INITIALIZED );\r
1615         /* CL_ASSERT that a find function is provided. */\r
1616         CL_ASSERT( pfn_func );\r
1617 \r
1618         return( cl_qlist_find_prev( p_list, cl_qlist_end( p_list ), pfn_func,\r
1619                 context ) );\r
1620 }\r
1621 /*\r
1622 * PARAMETERS\r
1623 *       p_list\r
1624 *               [in] Pointer to a cl_qlist_t structure.\r
1625 *\r
1626 *       pfn_func\r
1627 *               [in] Function invoked to determine if a match was found.\r
1628 *               See the cl_pfn_qlist_find_t function type declaration for details\r
1629 *               about the callback function.\r
1630 *\r
1631 *       context\r
1632 *               [in] Value to pass to the callback functions to provide context if a\r
1633 *               callback function is provided, or value compared to the quick list's\r
1634 *               list items.\r
1635 *\r
1636 * Returns:\r
1637 *       Pointer to the list item, if found.\r
1638 *\r
1639 *       Pointer to the list end otherwise\r
1640 *\r
1641 * NOTES\r
1642 *       cl_qlist_find_from_tail does not remove list items from the list.\r
1643 *       The list item is returned when the function specified by the pfn_func\r
1644 *       parameter returns CL_SUCCESS.\r
1645 *\r
1646 *       The function provided by the pfn_func parameter must not perform any list\r
1647 *       operations, as these would corrupt the list.\r
1648 *\r
1649 * SEE ALSO\r
1650 *       Quick List, cl_qlist_find_from_head, cl_qlist_find_next, cl_qlist_find_prev,\r
1651 *       cl_qlist_apply_func, cl_qlist_end, cl_qlist_move_items, cl_list_item_t,\r
1652 *       cl_pfn_qlist_find_t\r
1653 *********/\r
1654 \r
1655 \r
1656 /****f* Component Library: Quick List/cl_qlist_apply_func\r
1657 * NAME\r
1658 *       cl_qlist_apply_func\r
1659 *\r
1660 * DESCRIPTION\r
1661 *       The cl_qlist_apply_func function executes a specified function\r
1662 *       for every list item stored in a quick list.\r
1663 *\r
1664 * SYNOPSIS\r
1665 */\r
1666 CL_EXPORT void CL_API\r
1667 cl_qlist_apply_func(\r
1668         IN      const cl_qlist_t* const p_list,\r
1669         IN      cl_pfn_qlist_apply_t    pfn_func,\r
1670         IN      const void* const               context );\r
1671 /*\r
1672 * PARAMETERS\r
1673 *       p_list\r
1674 *               [in] Pointer to a cl_qlist_t structure.\r
1675 *\r
1676 *       pfn_func\r
1677 *               [in] Function invoked for every item in the quick list.\r
1678 *               See the cl_pfn_qlist_apply_t function type declaration for details\r
1679 *               about the callback function.\r
1680 *\r
1681 *       context\r
1682 *               [in] Value to pass to the callback functions to provide context.\r
1683 *\r
1684 * RETURN VALUE\r
1685 *       This function does not return a value.\r
1686 *\r
1687 * NOTES\r
1688 *       The function provided must not perform any list operations, as these\r
1689 *       would corrupt the quick list.\r
1690 *\r
1691 * SEE ALSO\r
1692 *       Quick List, cl_qlist_find_from_head, cl_qlist_find_from_tail,\r
1693 *       cl_qlist_move_items, cl_pfn_qlist_apply_t\r
1694 *********/\r
1695 \r
1696 \r
1697 /****f* Component Library: Quick List/cl_qlist_move_items\r
1698 * NAME\r
1699 *       cl_qlist_move_items\r
1700 *\r
1701 * DESCRIPTION\r
1702 *       The cl_qlist_move_items function moves list items from one list to\r
1703 *       another based on the return value of a user supplied function.\r
1704 *\r
1705 * SYNOPSIS\r
1706 */\r
1707 CL_EXPORT void CL_API\r
1708 cl_qlist_move_items(\r
1709         IN      cl_qlist_t* const       p_src_list,\r
1710         IN      cl_qlist_t* const       p_dest_list,\r
1711         IN      cl_pfn_qlist_find_t     pfn_func,\r
1712         IN      const void* const       context );\r
1713 /*\r
1714 * PARAMETERS\r
1715 *       p_src_list\r
1716 *               [in] Pointer to a cl_qlist_t structure from which\r
1717 *               list items are removed.\r
1718 *\r
1719 *       p_dest_list\r
1720 *               [in] Pointer to a cl_qlist_t structure to which the source\r
1721 *               list items are added.\r
1722 *\r
1723 *       pfn_func\r
1724 *               [in] Function invoked to determine if a match was found.\r
1725 *               See the cl_pfn_qlist_find_t function type declaration for details\r
1726 *               about the callback function.\r
1727 *\r
1728 *       context\r
1729 *               [in] Value to pass to the callback functions to provide context.\r
1730 *\r
1731 * RETURN VALUE\r
1732 *       This function does not return a value.\r
1733 *\r
1734 * NOTES\r
1735 *       If the function specified by the pfn_func parameter returns CL_SUCCESS,\r
1736 *       the related list item is removed from p_src_list and inserted at the tail\r
1737 *       of the p_dest_list.\r
1738 *\r
1739 *       The cl_qlist_move_items function continues iterating through p_src_list\r
1740 *       from the last item moved, allowing multiple items to be located and moved\r
1741 *       in a single list iteration.\r
1742 *\r
1743 *       The function specified by pfn_func must not perform any list operations,\r
1744 *       as these would corrupt the list.\r
1745 *\r
1746 * SEE ALSO\r
1747 *       Quick List, cl_qlist_find_from_head, cl_qlist_find_from_tail,\r
1748 *       cl_qlist_apply_func, cl_pfn_qlist_find_t\r
1749 *********/\r
1750 \r
1751 \r
1752 #ifdef __cplusplus\r
1753 }       /* extern "C" */\r
1754 #endif\r
1755 \r
1756 #endif /* _CL_QUICK_LIST_H_ */\r