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