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