[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_map.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 map, a binary tree.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_MAP_H_\r
44 #define _CL_MAP_H_\r
45 \r
46 \r
47 #include <complib/cl_qmap.h>\r
48 #include <complib/cl_qpool.h>\r
49 \r
50 \r
51 /****h* Component Library/Map\r
52 * NAME\r
53 *       Map\r
54 *\r
55 * DESCRIPTION\r
56 *       Map implements a binary tree that stores user objects.  Each item stored\r
57 *       in a map has a unique 64-bit key (duplicates are not allowed).  Map\r
58 *       provides the ability to efficiently search for an item given a key.\r
59 *\r
60 *       Map may allocate memory when inserting objects, and can therefore fail\r
61 *       operations due to insufficient memory.  Use quick map in situations where\r
62 *       such insertion failures cannot be tolerated.\r
63 *\r
64 *       Map is not thread safe, and users must provide serialization when adding\r
65 *       and removing items from the map.\r
66 *\r
67 *       The map functions operates on a cl_map_t structure which should be treated\r
68 *       as opaque and should be manipulated only through the provided functions.\r
69 *\r
70 * SEE ALSO\r
71 *       Types:\r
72 *               cl_map_iterator_t\r
73 *\r
74 *       Structures:\r
75 *               cl_map_t, cl_map_item_t, cl_map_obj_t\r
76 *\r
77 *       Item Manipulation:\r
78 *               cl_map_obj, cl_map_key\r
79 *\r
80 *       Initialization:\r
81 *               cl_map_construct, cl_map_init, cl_map_destroy\r
82 *\r
83 *       Iteration:\r
84 *               cl_map_end, cl_map_head, cl_map_tail, cl_map_next, cl_map_prev\r
85 *\r
86 *       Manipulation\r
87 *               cl_map_insert, cl_map_get, cl_map_remove_item, cl_map_remove,\r
88 *               cl_map_remove_all, cl_map_merge, cl_map_delta\r
89 *\r
90 *       Attributes:\r
91 *               cl_map_count, cl_is_map_empty, cl_is_map_inited\r
92 *********/\r
93 \r
94 \r
95 /****s* Component Library: Map/cl_map_t\r
96 * NAME\r
97 *       cl_map_t\r
98 *\r
99 * DESCRIPTION\r
100 *       Quick map structure.\r
101 *\r
102 *       The cl_map_t structure should be treated as opaque and should\r
103 *       be manipulated only through the provided functions.\r
104 *\r
105 * SYNOPSIS\r
106 */\r
107 typedef struct _cl_map\r
108 {\r
109         cl_qmap_t       qmap;\r
110         cl_qpool_t      pool;\r
111 \r
112 } cl_map_t;\r
113 /*\r
114 * FIELDS\r
115 *       qmap\r
116 *               Quick map object that maintains the map.\r
117 *\r
118 *       pool\r
119 *               Pool of cl_map_obj_t structures used to store user objects\r
120 *               in the map.\r
121 *\r
122 * SEE ALSO\r
123 *       Map, cl_map_obj_t\r
124 *********/\r
125 \r
126 \r
127 /****d* Component Library: Map/cl_map_iterator_t\r
128 * NAME\r
129 *       cl_map_iterator_t\r
130 *\r
131 * DESCRIPTION\r
132 *       Iterator type used to walk a map.\r
133 *\r
134 * SYNOPSIS\r
135 */\r
136 typedef const cl_map_item_t *cl_map_iterator_t;\r
137 /*\r
138 * NOTES\r
139 *       The iterator should be treated as opaque to prevent corrupting the map.\r
140 *\r
141 * SEE ALSO\r
142 *       Map, cl_map_head, cl_map_tail, cl_map_next, cl_map_prev, cl_map_key\r
143 *********/\r
144 \r
145 \r
146 #ifdef __cplusplus\r
147 extern "C" {\r
148 #endif\r
149 \r
150 \r
151 /****f* Component Library: Map/cl_map_count\r
152 * NAME\r
153 *       cl_map_count\r
154 *\r
155 * DESCRIPTION\r
156 *       The cl_map_count function returns the number of items stored\r
157 *       in a map.\r
158 *\r
159 * SYNOPSIS\r
160 */\r
161 CL_INLINE size_t CL_API\r
162 cl_map_count(\r
163         IN      const cl_map_t* const   p_map )\r
164 {\r
165         CL_ASSERT( p_map );\r
166         return( cl_qmap_count( &p_map->qmap ) );\r
167 }\r
168 /*\r
169 * PARAMETERS\r
170 *       p_map\r
171 *               [in] Pointer to a map whose item count to return.\r
172 *\r
173 * RETURN VALUE\r
174 *       Returns the number of items stored in the map.\r
175 *\r
176 * SEE ALSO\r
177 *       Map, cl_is_map_empty\r
178 *********/\r
179 \r
180 \r
181 /****f* Component Library: Map/cl_is_map_empty\r
182 * NAME\r
183 *       cl_is_map_empty\r
184 *\r
185 * DESCRIPTION\r
186 *       The cl_is_map_empty function returns whether a map is empty.\r
187 *\r
188 * SYNOPSIS\r
189 */\r
190 CL_INLINE boolean_t CL_API\r
191 cl_is_map_empty(\r
192         IN      const cl_map_t* const   p_map )\r
193 {\r
194         CL_ASSERT( p_map );\r
195         return( cl_is_qmap_empty( &p_map->qmap ) );\r
196 }\r
197 /*\r
198 * PARAMETERS\r
199 *       p_map\r
200 *               [in] Pointer to a map to test for emptiness.\r
201 *\r
202 * RETURN VALUES\r
203 *       TRUE if the map is empty.\r
204 *\r
205 *       FALSE otherwise.\r
206 *\r
207 * SEE ALSO\r
208 *       Map, cl_map_count, cl_map_remove_all\r
209 *********/\r
210 \r
211 \r
212 /****f* Component Library: Map/cl_map_key\r
213 * NAME\r
214 *       cl_map_key\r
215 *\r
216 * DESCRIPTION\r
217 *       The cl_map_key function retrieves the key value of a map item.\r
218 *\r
219 * SYNOPSIS\r
220 */\r
221 CL_INLINE uint64_t CL_API\r
222 cl_map_key(\r
223         IN      const cl_map_iterator_t itor )\r
224 {\r
225         return( cl_qmap_key( itor ) );\r
226 }\r
227 /*\r
228 * PARAMETERS\r
229 *       itor\r
230 *               [in] Iterator for the item whose key to return.\r
231 *\r
232 * RETURN VALUE\r
233 *       Returns the 64-bit key value for the specified iterator.\r
234 *\r
235 * NOTES\r
236 *       The iterator specified by the itor parameter must have been retrived by\r
237 *       a previous call to cl_map_head, cl_map_tail, cl_map_next, or cl_map_prev.\r
238 *\r
239 *       The key value is set in a call to cl_map_insert.\r
240 *\r
241 * SEE ALSO\r
242 *       Map, cl_map_insert, cl_map_head, cl_map_tail, cl_map_next, cl_map_prev\r
243 *********/\r
244 \r
245 \r
246 /****f* Component Library: Map/cl_map_construct\r
247 * NAME\r
248 *       cl_map_construct\r
249 *\r
250 * DESCRIPTION\r
251 *       The cl_map_construct function constructs a map.\r
252 *\r
253 * SYNOPSIS\r
254 */\r
255 CL_EXPORT void CL_API\r
256 cl_map_construct(\r
257         IN      cl_map_t* const p_map );\r
258 /*\r
259 * PARAMETERS\r
260 *       p_map\r
261 *               [in] Pointer to a cl_map_t structure to construct.\r
262 *\r
263 * RETURN VALUE\r
264 *       This function does not return a value.\r
265 *\r
266 * NOTES\r
267 *       Allows calling cl_map_init, cl_map_destroy, and cl_is_map_inited.\r
268 *\r
269 *       Calling cl_map_construct is a prerequisite to calling any other\r
270 *       map function except cl_map_init.\r
271 *\r
272 * SEE ALSO\r
273 *       Map, cl_map_init, cl_map_destroy, cl_is_map_inited\r
274 *********/\r
275 \r
276 \r
277 /****f* Component Library: Event/cl_is_map_inited\r
278 * NAME\r
279 *       cl_is_map_inited\r
280 *\r
281 * DESCRIPTION\r
282 *       The cl_is_map_inited function returns whether a map was\r
283 *       successfully initialized.\r
284 *\r
285 * SYNOPSIS\r
286 */\r
287 CL_INLINE boolean_t CL_API\r
288 cl_is_map_inited(\r
289         IN      const cl_map_t* const   p_map )\r
290 {\r
291         /*\r
292          * The map's pool of map items is the last thing initialized.\r
293          * We can therefore use it to test for initialization.\r
294          */\r
295         return( cl_is_qpool_inited( &p_map->pool ) );\r
296 }\r
297 /*\r
298 * PARAMETERS\r
299 *       p_map\r
300 *               [in] Pointer to a cl_map_t structure whose initialization state\r
301 *               to check.\r
302 *\r
303 * RETURN VALUES\r
304 *       TRUE if the map was initialized successfully.\r
305 *\r
306 *       FALSE otherwise.\r
307 *\r
308 * NOTES\r
309 *       Allows checking the state of a map to determine if invoking\r
310 *       member functions is appropriate.\r
311 *\r
312 * SEE ALSO\r
313 *       Map\r
314 *********/\r
315 \r
316 \r
317 /****f* Component Library: Map/cl_map_init\r
318 * NAME\r
319 *       cl_map_init\r
320 *\r
321 * DESCRIPTION\r
322 *       The cl_map_init function initialized a map for use.\r
323 *\r
324 * SYNOPSIS\r
325 */\r
326 CL_EXPORT cl_status_t CL_API\r
327 cl_map_init(\r
328         IN      cl_map_t* const p_map,\r
329         IN      const size_t    min_items );\r
330 /*\r
331 * PARAMETERS\r
332 *       p_map\r
333 *               [in] Pointer to a cl_map_t structure to initialize.\r
334 *\r
335 *       min_items\r
336 *               [in] Minimum number of items that can be stored.  All necessary\r
337 *               allocations to allow storing the minimum number of items is performed\r
338 *               at initialization time.\r
339 *\r
340 * RETURN VALUES\r
341 *       CL_SUCCESS if the map was initialized successfully.\r
342 *\r
343 * NOTES\r
344 *       Allows calling map manipulation functions.\r
345 *\r
346 * SEE ALSO\r
347 *       Map, cl_map_destroy, cl_map_insert, cl_map_remove\r
348 *********/\r
349 \r
350 \r
351 /****f* Component Library: Map/cl_map_destroy\r
352 * NAME\r
353 *       cl_map_destroy\r
354 *\r
355 * DESCRIPTION\r
356 *       The cl_map_destroy function destroys a map.\r
357 *\r
358 * SYNOPSIS\r
359 */\r
360 CL_EXPORT void CL_API\r
361 cl_map_destroy(\r
362         IN      cl_map_t* const p_map );\r
363 /*\r
364 * PARAMETERS\r
365 *       p_map\r
366 *               [in] Pointer to a map to destroy.\r
367 *\r
368 * RETURN VALUE\r
369 *       This function does not return a value.\r
370 *\r
371 * NOTES\r
372 *       Performs any necessary cleanup of the specified map. Further\r
373 *       operations should not be attempted on the map. cl_map_destroy does\r
374 *       not affect any of the objects stored in the map.\r
375 *       This function should only be called after a call to cl_map_construct.\r
376 *\r
377 *       In debug builds, cl_map_destroy asserts that the map is empty.\r
378 *\r
379 * SEE ALSO\r
380 *       Map, cl_map_construct, cl_map_init\r
381 *********/\r
382 \r
383 \r
384 /****f* Component Library: Map/cl_map_end\r
385 * NAME\r
386 *       cl_map_end\r
387 *\r
388 * DESCRIPTION\r
389 *       The cl_map_end function returns the iterator for the end of a map.\r
390 *\r
391 * SYNOPSIS\r
392 */\r
393 CL_INLINE const cl_map_iterator_t CL_API\r
394 cl_map_end(\r
395         IN      const cl_map_t* const   p_map )\r
396 {\r
397         CL_ASSERT( p_map );\r
398         return( cl_qmap_end( &p_map->qmap ) );\r
399 }\r
400 /*\r
401 * PARAMETERS\r
402 *       p_map\r
403 *               [in] Pointer to a cl_map_t structure whose end to return.\r
404 *\r
405 * RETURN VALUE\r
406 *       Iterator for the end of the map.\r
407 *\r
408 * NOTES\r
409 *       cl_map_end is useful for determining the validity of map items returned\r
410 *       by cl_map_head, cl_map_tail, cl_map_next, cl_map_prev.  If the iterator\r
411 *       by any of these functions compares to the end, the end of the map was\r
412 *       encoutered.\r
413 *       When using cl_map_head or cl_map_tail, this condition indicates that\r
414 *       the map is empty.\r
415 *\r
416 * SEE ALSO\r
417 *       Map, cl_qmap_head, cl_qmap_tail, cl_qmap_next, cl_qmap_prev\r
418 *********/\r
419 \r
420 \r
421 /****f* Component Library: Map/cl_map_head\r
422 * NAME\r
423 *       cl_map_head\r
424 *\r
425 * DESCRIPTION\r
426 *       The cl_map_head function returns the map item with the lowest key\r
427 *       value stored in a map.\r
428 *\r
429 * SYNOPSIS\r
430 */\r
431 CL_INLINE cl_map_iterator_t CL_API\r
432 cl_map_head(\r
433         IN      const cl_map_t* const   p_map )\r
434 {\r
435         CL_ASSERT( p_map );\r
436         return( cl_qmap_head( &p_map->qmap ) );\r
437 }\r
438 /*\r
439 * PARAMETERS\r
440 *       p_map\r
441 *               [in] Pointer to a map whose item with the lowest key is returned.\r
442 *\r
443 * RETURN VALUES\r
444 *       Iterator for the object with the lowest key in the map.\r
445 *\r
446 *       Iterator for the map end if the map was empty.\r
447 *\r
448 * NOTES\r
449 *       cl_map_head does not remove the object from the map.\r
450 *\r
451 * SEE ALSO\r
452 *       Map, cl_map_tail, cl_map_next, cl_map_prev, cl_map_end\r
453 *********/\r
454 \r
455 \r
456 /****f* Component Library: Map/cl_map_tail\r
457 * NAME\r
458 *       cl_map_tail\r
459 *\r
460 * DESCRIPTION\r
461 *       The cl_map_tail function returns the map item with the highest key\r
462 *       value stored in a map.\r
463 *\r
464 * SYNOPSIS\r
465 */\r
466 CL_INLINE cl_map_iterator_t CL_API\r
467 cl_map_tail(\r
468         IN      const cl_map_t* const   p_map )\r
469 {\r
470         CL_ASSERT( p_map );\r
471         return( cl_qmap_tail( &p_map->qmap ) );\r
472 }\r
473 /*\r
474 * PARAMETERS\r
475 *       p_map\r
476 *               [in] Pointer to a map whose item with the highest key\r
477 *               is returned.\r
478 *\r
479 * RETURN VALUES\r
480 *       Iterator for the object with the highest key in the map.\r
481 *\r
482 *       Iterator for the map end if the map was empty.\r
483 *\r
484 * NOTES\r
485 *       cl_map_end does no remove the object from the map.\r
486 *\r
487 * SEE ALSO\r
488 *       Map, cl_map_head, cl_map_next, cl_map_prev, cl_map_end\r
489 *********/\r
490 \r
491 \r
492 /****f* Component Library: Map/cl_map_next\r
493 * NAME\r
494 *       cl_map_next\r
495 *\r
496 * DESCRIPTION\r
497 *       The cl_map_next function returns the map item with the next higher\r
498 *       key value than a specified map item.\r
499 *\r
500 * SYNOPSIS\r
501 */\r
502 CL_INLINE cl_map_iterator_t CL_API\r
503 cl_map_next(\r
504         IN      const cl_map_iterator_t itor )\r
505 {\r
506         CL_ASSERT( itor );\r
507         return( cl_qmap_next( itor ) );\r
508 }\r
509 /*\r
510 * PARAMETERS\r
511 *       itor\r
512 *               [in] Iterator for an object in a map whose successor to return.\r
513 *\r
514 * RETURN VALUES\r
515 *       Iterator for the object with the next higher key value in a map.\r
516 *\r
517 *       Iterator for the map end if the specified object was the last item in\r
518 *       the map.\r
519 *\r
520 * NOTES\r
521 *       The iterator must have been retrieved by a previous call to cl_map_head,\r
522 *       cl_map_tail, cl_map_next, or cl_map_prev.\r
523 *\r
524 * SEE ALSO\r
525 *       Map, cl_map_head, cl_map_tail, cl_map_prev, cl_map_end\r
526 *********/\r
527 \r
528 \r
529 /****f* Component Library: Map/cl_map_prev\r
530 * NAME\r
531 *       cl_map_prev\r
532 *\r
533 * DESCRIPTION\r
534 *       The cl_map_prev function returns the map item with the next lower\r
535 *       key value than a precified map item.\r
536 *\r
537 * SYNOPSIS\r
538 */\r
539 CL_INLINE cl_map_iterator_t CL_API\r
540 cl_map_prev(\r
541         IN      const cl_map_iterator_t itor )\r
542 {\r
543         CL_ASSERT( itor );\r
544         return( cl_qmap_prev( itor ) );\r
545 }\r
546 /*\r
547 * PARAMETERS\r
548 *       itor\r
549 *               [in] Iterator for an object in a map whose predecessor to return.\r
550 *\r
551 * RETURN VALUES\r
552 *       Iterator for the object with the next lower key value in a map.\r
553 *\r
554 *       Iterator for the map end if the specified object was the first item in\r
555 *       the map.\r
556 *\r
557 * NOTES\r
558 *       The iterator must have been retrieved by a previous call to cl_map_head,\r
559 *       cl_map_tail, cl_map_next, or cl_map_prev.\r
560 *\r
561 * SEE ALSO\r
562 *       Map, cl_map_head, cl_map_tail, cl_map_next, cl_map_end\r
563 *********/\r
564 \r
565 \r
566 /****f* Component Library: Map/cl_map_insert\r
567 * NAME\r
568 *       cl_map_insert\r
569 *\r
570 * DESCRIPTION\r
571 *       The cl_map_insert function inserts a map item into a map.\r
572 *\r
573 * SYNOPSIS\r
574 */\r
575 CL_EXPORT void* CL_API\r
576 cl_map_insert(\r
577         IN      cl_map_t* const         p_map,\r
578         IN      const uint64_t          key,\r
579         IN      const void* const       p_object );\r
580 /*\r
581 * PARAMETERS\r
582 *       p_map\r
583 *               [in] Pointer to a map into which to add the item.\r
584 *\r
585 *       key\r
586 *               [in] Value to associate with the object.\r
587 *\r
588 *       p_object\r
589 *               [in] Pointer to an object to insert into the map.\r
590 *\r
591 * RETURN VALUES\r
592 *       Pointer to the object in the map with the specified key after the call\r
593 *       completes.\r
594 *\r
595 *       NULL if there was not enough memory to insert the desired item.\r
596 *\r
597 * NOTES\r
598 *       Insertion operations may cause the map to rebalance.\r
599 *\r
600 *       If the map already contains an object already with the specified key,\r
601 *       that object will not be replaced and the pointer to that object is\r
602 *       returned.\r
603 *\r
604 * SEE ALSO\r
605 *       Map, cl_map_remove, cl_map_item_t\r
606 *********/\r
607 \r
608 \r
609 /****f* Component Library: Map/cl_map_get\r
610 * NAME\r
611 *       cl_map_get\r
612 *\r
613 * DESCRIPTION\r
614 *       The cl_map_get function returns the object associated with a key.\r
615 *\r
616 * SYNOPSIS\r
617 */\r
618 CL_EXPORT void* CL_API\r
619 cl_map_get(\r
620         IN      const cl_map_t* const   p_map,\r
621         IN      const uint64_t                  key );\r
622 /*\r
623 * PARAMETERS\r
624 *       p_map\r
625 *               [in] Pointer to a map from which to retrieve the object with\r
626 *               the specified key.\r
627 *\r
628 *       key\r
629 *               [in] Key value used to search for the desired object.\r
630 *\r
631 * RETURN VALUES\r
632 *       Pointer to the object with the desired key value.\r
633 *\r
634 *       NULL if there was no item with the desired key value stored in\r
635 *       the map.\r
636 *\r
637 * NOTES\r
638 *       cl_map_get does not remove the item from the map.\r
639 *\r
640 * SEE ALSO\r
641 *       Map, cl_map_remove\r
642 *********/\r
643 \r
644 \r
645 /****f* Component Library: Map/cl_map_remove_item\r
646 * NAME\r
647 *       cl_map_remove_item\r
648 *\r
649 * DESCRIPTION\r
650 *       The cl_map_remove_item function removes the specified map item\r
651 *       from a map.\r
652 *\r
653 * SYNOPSIS\r
654 */\r
655 CL_EXPORT void CL_API\r
656 cl_map_remove_item(\r
657         IN      cl_map_t* const                 p_map,\r
658         IN      const cl_map_iterator_t itor );\r
659 /*\r
660 * PARAMETERS\r
661 *       p_map\r
662 *               [in] Pointer to a map from which to remove the object associated with\r
663 *               the specified iterator.\r
664 *\r
665 *       itor\r
666 *               [in] Iterator for an object to remove from its map.\r
667 *\r
668 * RETURN VALUE\r
669 *       This function does not return a value.\r
670 *\r
671 * NOTES\r
672 *       Removes the object associated with the specifid iterator from its map.\r
673 *\r
674 *       The specified iterator is no longer valid after the call completes.\r
675 *\r
676 *       The iterator must have been retrieved by a previous call to cl_map_head,\r
677 *       cl_map_tail, cl_map_next, or cl_map_prev.\r
678 *\r
679 * SEE ALSO\r
680 *       Map, cl_map_remove, cl_map_remove_all, cl_map_insert, cl_map_head,\r
681 *       cl_map_tail, cl_map_next, cl_map_prev\r
682 *********/\r
683 \r
684 \r
685 /****f* Component Library: Map/cl_map_remove\r
686 * NAME\r
687 *       cl_map_remove\r
688 *\r
689 * DESCRIPTION\r
690 *       The cl_map_remove function removes the map item with the specified key\r
691 *       from a map.\r
692 *\r
693 * SYNOPSIS\r
694 */\r
695 CL_EXPORT void* CL_API\r
696 cl_map_remove(\r
697         IN      cl_map_t* const p_map,\r
698         IN      const uint64_t  key );\r
699 /*\r
700 * PARAMETERS\r
701 *       p_map\r
702 *               [in] Pointer to a cl_map_t structure from which to remove the item\r
703 *               with the specified key.\r
704 *\r
705 *       key\r
706 *               [in] Key value used to search for the object to remove.\r
707 *\r
708 * RETURN VALUES\r
709 *       Pointer to the object associated with the specified key if\r
710 *       it was found and removed.\r
711 *\r
712 *       NULL if no object with the specified key exists in the map.\r
713 *\r
714 * SEE ALSO\r
715 *       Map, cl_map_remove_item, cl_map_remove_all, cl_map_insert\r
716 *********/\r
717 \r
718 \r
719 /****f* Component Library: Map/cl_map_remove_all\r
720 * NAME\r
721 *       cl_map_remove_all\r
722 *\r
723 * DESCRIPTION\r
724 *       The cl_map_remove_all function removes all objects from a map,\r
725 *       leaving it empty.\r
726 *\r
727 * SYNOPSIS\r
728 */\r
729 CL_EXPORT void CL_API\r
730 cl_map_remove_all(\r
731         IN      cl_map_t* const p_map );\r
732 /*\r
733 * PARAMETERS\r
734 *       p_map\r
735 *               [in] Pointer to a map to empty.\r
736 *\r
737 * RETURN VALUE\r
738 *       This function does not return a value.\r
739 *\r
740 * SEE ALSO\r
741 *       Map, cl_map_remove, cl_map_remove_item\r
742 *********/\r
743 \r
744 \r
745 /****f* Component Library: Map/cl_map_obj\r
746 * NAME\r
747 *       cl_map_obj\r
748 *\r
749 * DESCRIPTION\r
750 *       The cl_map_obj function returns the object associated with an iterator.\r
751 *\r
752 * SYNOPSIS\r
753 */\r
754 CL_INLINE void* CL_API\r
755 cl_map_obj(\r
756         IN      const cl_map_iterator_t itor )\r
757 {\r
758         return( cl_qmap_obj( PARENT_STRUCT( itor, cl_map_obj_t, item ) ) );\r
759 }\r
760 /*\r
761 * PARAMETERS\r
762 *       itor\r
763 *               [in] Iterator whose object to return.\r
764 *\r
765 * RETURN VALUES\r
766 *       Returns the value of the object pointer associated with the iterator.\r
767 *\r
768 *       The iterator must have been retrieved by a previous call to cl_map_head,\r
769 *       cl_map_tail, cl_map_next, or cl_map_prev.\r
770 *\r
771 * SEE ALSO\r
772 *       Map, cl_map_head, cl_map_tail, cl_map_next, cl_map_prev\r
773 *********/\r
774 \r
775 \r
776 /****f* Component Library: Map/cl_map_merge\r
777 * NAME\r
778 *       cl_map_merge\r
779 *\r
780 * DESCRIPTION\r
781 *       The cl_map_merge function moves all items from one map to another,\r
782 *       excluding duplicates.\r
783 *\r
784 * SYNOPSIS\r
785 */\r
786 CL_EXPORT cl_status_t CL_API\r
787 cl_map_merge(\r
788         OUT             cl_map_t* const p_dest_map,\r
789         IN OUT  cl_map_t* const p_src_map );\r
790 /*\r
791 * PARAMETERS\r
792 *       p_dest_map\r
793 *               [out] Pointer to a cl_map_t structure to which items should be added.\r
794 *\r
795 *       p_src_map\r
796 *               [in/out] Pointer to a cl_map_t structure whose items to add\r
797 *               to p_dest_map.\r
798 *\r
799 * RETURN VALUES\r
800 *       CL_SUCCESS if the operation succeeded.\r
801 *\r
802 *       CL_INSUFFICIENT_MEMORY if there was not enough memory for the operation\r
803 *       to succeed.\r
804 *\r
805 * NOTES\r
806 *       Items are evaluated based on their keys only.\r
807 *\r
808 *       Upon return from cl_map_merge, the map referenced by p_src_map contains\r
809 *       all duplicate items.\r
810 *\r
811 * SEE ALSO\r
812 *       Map, cl_map_delta\r
813 *********/\r
814 \r
815 \r
816 /****f* Component Library: Map/cl_map_delta\r
817 * NAME\r
818 *       cl_map_delta\r
819 *\r
820 * DESCRIPTION\r
821 *       The cl_map_delta function computes the differences between two maps.\r
822 *\r
823 * SYNOPSIS\r
824 */\r
825 CL_EXPORT cl_status_t CL_API\r
826 cl_map_delta(\r
827         IN OUT  cl_map_t* const p_map1,\r
828         IN OUT  cl_map_t* const p_map2,\r
829         OUT             cl_map_t* const p_new,\r
830         OUT             cl_map_t* const p_old );\r
831 /*\r
832 * PARAMETERS\r
833 *       p_map1\r
834 *               [in/out] Pointer to the first of two cl_map_t structures whose\r
835 *               differences to compute.\r
836 *\r
837 *       p_map2\r
838 *               [in/out] Pointer to the second of two cl_map_t structures whose\r
839 *               differences to compute.\r
840 *\r
841 *       p_new\r
842 *               [out] Pointer to an empty cl_map_t structure that contains the items\r
843 *               unique to p_map2 upon return from the function.\r
844 *\r
845 *       p_old\r
846 *               [out] Pointer to an empty cl_map_t structure that contains the items\r
847 *               unique to p_map1 upon return from the function.\r
848 *\r
849 * RETURN VALUES\r
850 *       CL_SUCCESS if the operation succeeded.\r
851 *\r
852 *       CL_INSUFFICIENT_MEMORY if there was not enough memory for the operation\r
853 *       to succeed.\r
854 *\r
855 * NOTES\r
856 *       Items are evaluated based on their keys.  Items that exist in both\r
857 *       p_map1 and p_map2 remain in their respective maps.  Items that\r
858 *       exist only p_map1 are moved to p_old.  Likewise, items that exist only\r
859 *       in p_map2 are moved to p_new.  This function can be usefull in evaluating\r
860 *       changes between two maps.\r
861 *\r
862 *       Both maps pointed to by p_new and p_old must be empty on input.\r
863 *\r
864 *       Upon failure, all input maps are restored to their original state.\r
865 *\r
866 * SEE ALSO\r
867 *       Map, cl_map_merge\r
868 *********/\r
869 \r
870 \r
871 #ifdef __cplusplus\r
872 }\r
873 #endif\r
874 \r
875 #endif  /* _CL_MAP_H_ */\r