1/*
2 * Copyright (c) 2019 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28/* IOSet.h created by rsulack on Thu 11-Jun-1998 */
29/* IOSet.h converted to C++ by gvdl on Fri 1998-10-30 */
30
31#ifndef _OS_OSSET_H
32#define _OS_OSSET_H
33
34#include <libkern/c++/OSCollection.h>
35#include <libkern/c++/OSPtr.h>
36
37class OSArray;
38class OSSet;
39
40typedef OSSet* OSSetPtr;
41typedef OSArray* OSArrayPtr;
42
43/*!
44 * @header
45 *
46 * @abstract
47 * This header declares the OSSet collection class.
48 */
49
50
51/*!
52 * @class OSSet
53 *
54 * @abstract
55 * OSSet provides an unordered set store of objects.
56 *
57 * @discussion
58 * OSSet is a container for Libkern C++ objects
59 * (those derived from
60 * @link //apple_ref/doc/class/OSMetaClassBase OSMetaClassBase@/link,
61 * in particular @link //apple_ref/doc/class/OSObject OSObject@/link).
62 * Storage and access follow basic set logic: you can add or remove an object,
63 * and test whether the set contains a particular object.
64 * A given object is only stored in the set once,
65 * and there is no ordering of objects in the set.
66 * A subclass @link //apple_ref/doc/class/OSOrderedSet OSOrderedSet@/link,
67 * provides for ordered set logic.
68 *
69 * As with all Libkern collection classes,
70 * OSSet retains objects added to it,
71 * and releases objects removed from it.
72 * An OSSet also grows as necessary to accommodate new objects,
73 * <i>unlike</i> Core Foundation collections (it does not, however, shrink).
74 *
75 * <b>Use Restrictions</b>
76 *
77 * With very few exceptions in the I/O Kit, all Libkern-based C++
78 * classes, functions, and macros are <b>unsafe</b>
79 * to use in a primary interrupt context.
80 * Consult the I/O Kit documentation related to primary interrupts
81 * for more information.
82 *
83 * OSSet provides no concurrency protection;
84 * it's up to the usage context to provide any protection necessary.
85 * Some portions of the I/O Kit, such as
86 * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link,
87 * handle synchronization via defined member functions for setting
88 * properties.
89 */
90class OSSet : public OSCollection
91{
92 friend class OSSerialize;
93
94 OSDeclareDefaultStructors(OSSet);
95
96#if APPLE_KEXT_ALIGN_CONTAINERS
97
98private:
99 OSPtr<OSArray> members;
100
101#else /* APPLE_KEXT_ALIGN_CONTAINERS */
102
103private:
104 OSPtr<OSArray> members;
105
106protected:
107 struct ExpansionData { };
108
109/* Reserved for future use. (Internal use only) */
110 ExpansionData * reserved;
111
112#endif /* APPLE_KEXT_ALIGN_CONTAINERS */
113
114/*
115 * OSCollectionIterator interfaces.
116 */
117 virtual unsigned int iteratorSize() const APPLE_KEXT_OVERRIDE;
118 virtual bool initIterator(void * iterator) const APPLE_KEXT_OVERRIDE;
119 virtual bool getNextObjectForIterator(void * iterator, OSObject ** ret) const APPLE_KEXT_OVERRIDE;
120
121public:
122
123
124/*!
125 * @function withCapacity
126 *
127 * @abstract
128 * Creates and initializes an empty OSSet.
129 *
130 * @param capacity The initial storage capacity of the new set object.
131 *
132 * @result
133 * An empty instance of OSSet
134 * with a retain count of 1;
135 * <code>NULL</code> on failure.
136 *
137 * @discussion
138 * <code>capacity</code> must be nonzero.
139 * The new OSSet will grow as needed to accommodate more key/object pairs
140 * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link,
141 * for which the initial capacity is a hard limit).
142 */
143 static OSPtr<OSSet> withCapacity(unsigned int capacity);
144
145
146/*!
147 * @function withObjects
148 *
149 * @abstract
150 * Creates and initializes an OSSet
151 * populated with objects provided.
152 *
153 * @param objects A C array of OSMetaClassBase-derived objects.
154 * @param count The number of objects to be placed into the set.
155 * @param capacity The initial storage capacity of the new set object.
156 * If 0, <code>count</code> is used; otherwise this value
157 * must be greater than or equal to <code>count</code>.
158 *
159 * @result
160 * An instance of OSSet
161 * containing the objects provided,
162 * with a retain count of 1;
163 * <code>NULL</code> on failure.
164 *
165 * @discussion
166 * <code>objects</code> must be non-<code>NULL</code>,
167 * and <code>count</code> must be nonzero.
168 * If <code>capacity</code> is nonzero,
169 * it must be greater than or equal to <code>count</code>.
170 * The new OSSet will grow as needed to accommodate more objects
171 * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link,
172 * for which the initial capacity is a hard limit).
173 *
174 * The objects in <code>objects</code> are retained for storage in the new set,
175 * not copied.
176 */
177 static OSPtr<OSSet> withObjects(
178 const OSObject * objects[],
179 unsigned int count,
180 unsigned int capacity = 0);
181
182
183/*!
184 * @function withArray
185 *
186 * @abstract
187 * Creates and initializes an OSSet
188 * populated with the contents of an OSArray.
189 *
190 * @param array An array whose objects will be stored in the new OSSet.
191 * @param capacity The initial storage capacity of the new set object.
192 * If 0, the capacity is set to the number of objects
193 * in <code>array</code>;
194 * otherwise <code>capacity</code> must be greater than or equal to
195 * the number of objects in <code>array</code>.
196 * @result
197 * An instance of OSSet containing
198 * the objects of <code>array</code>,
199 * with a retain count of 1;
200 * <code>NULL</code> on failure.
201 *
202 * @discussion
203 * Each distinct object in <code>array</code> is added to the new set.
204 *
205 * <code>array</code> must be non-<code>NULL</code>.
206 * If <code>capacity</code> is nonzero,
207 * it must be greater than or equal to <code>count</code>.
208 * The new OSSet will grow as needed to accommodate more key-object pairs
209 * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link,
210 * for which the initial capacity is a hard limit).
211 *
212 * The objects in <code>array</code> are retained for storage in the new set,
213 * not copied.
214 */
215 static OSPtr<OSSet> withArray(
216 const OSArray * array,
217 unsigned int capacity = 0);
218
219
220/*!
221 * @function withSet
222 *
223 * @abstract
224 * Creates and initializes an OSSet
225 * populated with the contents of another OSSet.
226 *
227 * @param set An OSSet whose contents will be stored
228 * in the new instance.
229 * @param capacity The initial storage capacity of the set object.
230 * If 0, the capacity is set to the number of objects
231 * in <code>set</code>;
232 * otherwise <code>capacity</code> must be greater than or equal to
233 * the number of objects in <code>array</code>.
234 * @result
235 * An instance of OSArray
236 * containing the objects of <code>set</code>,
237 * with a retain count of 1;
238 * <code>NULL</code> on failure.
239 *
240 * @discussion
241 * <code>set</code> must be non-<code>NULL</code>.
242 * If <code>capacity</code> is nonzero,
243 * it must be greater than or equal to <code>count</code>.
244 * The array will grow as needed to accommodate more key-object pairs
245 * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link,
246 * for which the initial capacity is a hard limit).
247 *
248 * The objects in <code>set</code> are retained for storage in the new set,
249 * not copied.
250 */
251 static OSPtr<OSSet> withSet(const OSSet * set,
252 unsigned int capacity = 0);
253
254
255/*!
256 * @function initWithCapacity
257 *
258 * @abstract
259 * Initializes a new instance of OSSet.
260 *
261 * @param capacity The initial storage capacity of the new set object.
262 *
263 * @result
264 * <code>true</code> on success, <code>false</code> on failure.
265 *
266 * @discussion
267 * Not for general use. Use the static instance creation method
268 * <code>@link
269 * //apple_ref/cpp/clm/OSSet/withCapacity/staticOSSet*\/(unsignedint)
270 * withCapacity@/link</code>
271 * instead.
272 *
273 * <code>capacity</code> must be nonzero.
274 * The new set will grow as needed to accommodate more key/object pairs
275 * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link,
276 * for which the initial capacity is a hard limit).
277 */
278 virtual bool initWithCapacity(unsigned int capacity);
279
280
281/*!
282 * @function initWithObjects
283 *
284 * @abstract
285 * Initializes a new OSSet populated with objects provided.
286 *
287 * @param objects A C array of OSObject-derived objects.
288 * @param count The number of objects to be placed into the set.
289 * @param capacity The initial storage capacity of the new set object.
290 * If 0, <code>count</code> is used; otherwise this value
291 * must be greater than or equal to <code>count</code>.
292 *
293 * @result
294 * <code>true</code> on success, <code>false</code> on failure.
295 *
296 * @discussion
297 * Not for general use. Use the static instance creation method
298 * <code>@link
299 * //apple_ref/cpp/clm/OSSet/withObjects/staticOSSet*\/(constOSObject*,unsignedint,unsignedint)
300 * withObjects@/link</code>
301 * instead.
302 *
303 * <code>objects</code> must be non-<code>NULL</code>,
304 * and <code>count</code> must be nonzero.
305 * If <code>capacity</code> is nonzero, it must be greater than or equal to <code>count</code>.
306 * The new array will grow as needed to accommodate more key-object pairs
307 * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link,
308 * for which the initial capacity is a hard limit).
309 *
310 * The objects in <code>objects</code> are retained for storage in the new set,
311 * not copied.
312 */
313 virtual bool initWithObjects(
314 const OSObject * objects[],
315 unsigned int count,
316 unsigned int capacity = 0);
317
318
319/*!
320 * @function initWithArray
321 *
322 * @abstract Initializes a new OSSet
323 * populated with the contents of an OSArray.
324 *
325 * @param array An OSAray whose contents will be placed
326 * in the new instance.
327 * @param capacity The initial storage capacity of the new set object.
328 * If 0, the capacity is set
329 * to the number of objects in <code>array</code>;
330 * otherwise <code>capacity</code> must be greater than or equal to
331 * the number of objects in <code>array</code>.
332 *
333 * @result
334 * <code>true</code> on success, <code>false</code> on failure.
335 *
336 * @discussion
337 * Not for general use. Use the static instance creation method
338 * <code>@link
339 * //apple_ref/cpp/clm/OSSet/withArray/staticOSSet*\/(constOSArray*,unsignedint)
340 * withArray@/link</code>
341 * instead.
342 *
343 * <code>array</code> must be non-<code>NULL</code>.
344 * If <code>capacity</code> is nonzero,
345 * it must be greater than or equal to <code>count</code>.
346 * The new array will grow as needed to accommodate more key-object pairs
347 * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link,
348 * for which the initial capacity is a hard limit).
349 *
350 * The objects in <code>array</code> are retained for storage in the new set,
351 * not copied.
352 */
353 virtual bool initWithArray(
354 const OSArray * array,
355 unsigned int capacity = 0);
356
357
358/*!
359 * @function initWithSet
360 *
361 * @abstract
362 * Initializes a new OSSet
363 * populated with the contents of another OSSet.
364 *
365 * @param set A set whose contents will be placed in the new instance.
366 * @param capacity The initial storage capacity of the new set object.
367 * If 0, the capacity is set
368 * to the number of objects in <code>set</code>;
369 * otherwise <code>capacity</code> must be greater than or equal to
370 * the number of objects in <code>set</code>.
371 *
372 * @result
373 * <code>true</code> on success, <code>false</code> on failure.
374 *
375 * @discussion
376 * Not for general use. Use the static instance creation method
377 * <code>@link withSet withSet@/link</code> instead.
378 *
379 * <code>set</code> must be non-<code>NULL</code>.
380 * If <code>capacity</code> is nonzero,
381 * it must be greater than or equal to <code>count</code>.
382 * The new set will grow as needed to accommodate more key-object pairs
383 * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link,
384 * for which the initial capacity is a hard limit).
385 *
386 * The objects in <code>set</code> are retained for storage in the new set,
387 * not copied.
388 */
389 virtual bool initWithSet(const OSSet *set,
390 unsigned int capacity = 0);
391
392
393/*!
394 * @function free
395 *
396 * @abstract
397 * Deallocates or releases any resources
398 * used by the OSSet instance.
399 *
400 * @discussion
401 * This function should not be called directly;
402 * use
403 * <code>@link
404 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
405 * release@/link</code>
406 * instead.
407 */
408 virtual void free() APPLE_KEXT_OVERRIDE;
409
410
411/*!
412 * @function getCount
413 *
414 * @abstract
415 * Returns the current number of objects within the set.
416 *
417 * @result
418 * The current number of objects within the set.
419 */
420 virtual unsigned int getCount() const APPLE_KEXT_OVERRIDE;
421
422
423/*!
424 * @function getCapacity
425 *
426 * @abstract
427 * Returns the number of objects the set
428 * can store without reallocating.
429 *
430 * @result
431 * The number objects the set
432 * can store without reallocating.
433 *
434 * @discussion
435 * OSSet objects grow when full to accommodate additional objects.
436 * See
437 * <code>@link
438 * //apple_ref/cpp/instm/OSSet/getCapacityIncrement/virtualunsignedint/()
439 * getCapacityIncrement@/link</code>
440 * and
441 * <code>@link
442 * //apple_ref/cpp/instm/OSSet/ensureCapacity/virtualunsignedint/(unsignedint)
443 * ensureCapacity@/link</code>.
444 */
445 virtual unsigned int getCapacity() const APPLE_KEXT_OVERRIDE;
446
447
448/*!
449 * @function getCapacityIncrement
450 *
451 * @abstract
452 * Returns the storage increment of the set.
453 *
454 * @result
455 * The storage increment of the set.
456 *
457 * @discussion
458 * An OSSet allocates storage for objects in multiples
459 * of the capacity increment.
460 */
461 virtual unsigned int getCapacityIncrement() const APPLE_KEXT_OVERRIDE;
462
463
464/*!
465 * @function setCapacityIncrement
466 *
467 * @abstract
468 * Sets the storage increment of the set.
469 *
470 * @result
471 * The new storage increment of the set,
472 * which may be different from the number requested.
473 *
474 * @discussion
475 * An OSSet allocates storage for objects in multiples
476 * of the capacity increment.
477 * Calling this function does not immediately reallocate storage.
478 */
479 virtual unsigned int setCapacityIncrement(unsigned increment) APPLE_KEXT_OVERRIDE;
480
481
482/*!
483 * @function ensureCapacity
484 *
485 * @abstract
486 * Ensures the set has enough space
487 * to store the requested number of distinct objects.
488 *
489 * @param newCapacity The total number of distinct objects the set
490 * should be able to store.
491 * @result
492 * The new capacity of the set,
493 * which may be different from the number requested
494 * (if smaller, reallocation of storage failed).
495 *
496 * @discussion
497 * This function immediately resizes the set, if necessary,
498 * to accommodate at least <code>newCapacity</code> distinct objects.
499 * If <code>newCapacity</code> is not greater than the current capacity,
500 * or if an allocation error occurs, the original capacity is returned.
501 *
502 * There is no way to reduce the capacity of an OSSet.
503 */
504 virtual unsigned int ensureCapacity(unsigned int newCapacity) APPLE_KEXT_OVERRIDE;
505
506
507/*!
508 * @function flushCollection
509 *
510 * @abstract
511 * Removes and releases all objects within the set.
512 *
513 * @discussion
514 * The set's capacity (and therefore direct memory consumption)
515 * is not reduced by this function.
516 */
517 virtual void flushCollection() APPLE_KEXT_OVERRIDE;
518
519
520/*!
521 * @function setObject
522 *
523 * @abstract
524 * Adds an object to the OSSet if it is not already present.
525 *
526 * @param anObject The OSMetaClassBase-derived object to be added to the set.
527 *
528 * @result
529 * <code>true</code> if <code>anObject</code> was successfully
530 * added to the set, <code>false</code> otherwise
531 * (including if it was already in the set).
532 *
533 * @discussion
534 * The set adds storage to accomodate the new object, if necessary.
535 * If successfully added, the object is retained.
536 *
537 * A <code>false</code> return value can mean either
538 * that <code>anObject</code> is already present in the set,
539 * or that a memory allocation failure occurred.
540 * If you need to know whether the object
541 * is already present, use
542 * <code>@link containsObject containsObject@/link</code>.
543 */
544 virtual bool setObject(const OSMetaClassBase * anObject);
545
546 bool setObject(OSSharedPtr<const OSMetaClassBase> const& anObject);
547
548
549/*!
550 * @function merge
551 *
552 * @abstract
553 * Adds the contents of an OSArray to the set.
554 *
555 * @param array The OSArray object containing the objects to be added.
556 *
557 * @result
558 * <code>true</code> if all objects from <code>array</code>
559 * are successfully added the receiver (or were already present),
560 * <code>false</code> otherwise.
561 *
562 * @discussion
563 * This functions adds to the receiving set
564 * all objects from <code>array</code>
565 * that are not already in the receiving set.
566 * Objects added to the receiver are retained.
567 *
568 * In releases prior to 10.7, this function would return <code>false</code>
569 * if an object from <code>array</code> was already present in the set,
570 * or if <code>array</code> was empty.
571 * This is no longer the case, so this function correctly returns <code>true</code>
572 * when the semantic of merging is met.
573 */
574 virtual bool merge(const OSArray * array);
575
576
577/*!
578 * @function merge
579 *
580 * @abstract
581 * Adds the contents of an OSet to the set.
582 *
583 * @param set The OSSet object containing the objects to be added.
584 *
585 * @result
586 * <code>true</code> if any object from <code>set</code>
587 * are successfully added the receiver (or were already present),
588 * <code>false</code> otherwise.
589 *
590 * @discussion
591 * This functions adds to the receiving set
592 * all objects from <code>set</code>
593 * that are not already in the receiving set.
594 * Objects added to the receiver are retained.
595 *
596 * In releases prior to 10.7, this function would return <code>false</code>
597 * if an object from <code>set</code> was already present in the set,
598 * or if <code>set</code> was empty.
599 * This is no longer the case, so this function correctly returns <code>true</code>
600 * when the semantic of merging is met.
601 */
602 virtual bool merge(const OSSet * set);
603
604
605/*!
606 * @function removeObject
607 *
608 * @abstract
609 * Removes an object from the set.
610 *
611 * @param anObject The OSMetaClassBase-derived object
612 * to be removed from the set.
613 *
614 * @discussion
615 * The object removed from the set is released.
616 */
617 virtual void removeObject(const OSMetaClassBase * anObject);
618
619 void removeObject(OSSharedPtr<const OSMetaClassBase> const& anObject);
620
621
622/*!
623 * @function containsObject
624 *
625 * @abstract
626 * Checks the set for the presence of an object.
627 *
628 * @param anObject The OSMetaClassBase-derived object
629 * to check for in the set.
630 *
631 * @result
632 * <code>true</code> if <code>anObject</code> is present within the set,
633 * <code>false</code> otherwise.
634 *
635 * @discussion
636 * Pointer equality is used.
637 * This function returns <code>false</code> if passed <code>NULL</code>.
638 */
639 virtual bool containsObject(const OSMetaClassBase * anObject) const;
640
641
642/*!
643 * @function member
644 *
645 * @abstract
646 * Checks the set for the presence of an object.
647 *
648 * @param anObject The OSMetaClassBase-derived object
649 * to check for in the set.
650 *
651 * @result
652 * <code>true</code> if <code>anObject</code> is present
653 * within the set, <code>false</code> otherwise.
654 *
655 * @discussion
656 * Pointer equality is used. This function returns <code>false</code>
657 * if passed <code>NULL</code>.
658 *
659 * <code>@link containsObject containsObject@/link</code>
660 * checks for <code>NULL</code> first,
661 * and is therefore more efficient than this function.
662 */
663 virtual bool member(const OSMetaClassBase * anObject) const;
664
665
666/*!
667 * @function getAnyObject
668 *
669 * @abstract
670 * Returns an arbitrary (not random) object from the set.
671 *
672 * @result
673 * An arbitrary (not random) object
674 * if one exists within the set.
675 *
676 * @discussion
677 * The returned object will be released if removed from the set;
678 * if you plan to store the reference, you should call
679 * <code>@link
680 * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
681 * retain@/link</code>
682 * on that object.
683 */
684 virtual OSObject * getAnyObject() const;
685
686
687/*!
688 * @function isEqualTo
689 *
690 * @abstract
691 * Tests the equality of two OSSet objects.
692 *
693 * @param aSet The set object being compared against the receiver.
694 * @result
695 * <code>true</code> if the two sets are equivalent,
696 * <code>false</code> otherwise.
697 *
698 * @discussion
699 * Two OSSet objects are considered equal if they have same count
700 * and the same object pointer values.
701 */
702 virtual bool isEqualTo(const OSSet * aSet) const;
703
704
705/*!
706 * @function isEqualTo
707 *
708 * @abstract
709 * Tests the equality of an OSSet against an arbitrary object.
710 *
711 * @param anObject The object being compared against the receiver.
712 * @result
713 * <code>true</code> if the two objects are equivalent,
714 * <code>false</code> otherwise.
715 *
716 * @discussion
717 * An OSSet object is considered equal to another object if the other object
718 * is derived from OSSet and compares equal as a set.
719 */
720 virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE;
721
722
723/*!
724 * @function serialize
725 *
726 * @abstract
727 * Archives the receiver into the provided
728 * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
729 *
730 * @param serializer The OSSerialize object.
731 *
732 * @result
733 * <code>true</code> if serialization succeeds, <code>false</code> if not.
734 */
735 virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE;
736
737
738/*!
739 * @function setOptions
740 *
741 * @abstract
742 * Recursively sets option bits in the set
743 * and all child collections.
744 *
745 * @param options A bitfield whose values turn the options on (1) or off (0).
746 * @param mask A mask indicating which bits
747 * in <code>options</code> to change.
748 * Pass 0 to get the whole current options bitfield
749 * without changing any settings.
750 * @param context Unused.
751 *
752 * @result
753 * The options bitfield as it was before the set operation.
754 *
755 * @discussion
756 * Kernel extensions should not call this function.
757 *
758 * Child collections' options are changed only if the receiving set's
759 * options actually change.
760 */
761 virtual unsigned setOptions(unsigned options, unsigned mask, void * context = NULL) APPLE_KEXT_OVERRIDE;
762
763
764/*!
765 * @function copyCollection
766 *
767 * @abstract
768 * Creates a deep copy of this set and its child collections.
769 *
770 * @param cycleDict A dictionary of all of the collections
771 * that have been copied so far,
772 * which is used to track circular references.
773 * To start the copy at the top level,
774 * pass <code>NULL</code>.
775 *
776 * @result
777 * The newly copied set, with a retain count of 1,
778 * or <code>NULL</code> if there is insufficient memory to do the copy.
779 *
780 * @discussion
781 * The receiving set, and any collections it contains,
782 * recursively, are copied.
783 * Objects that are not derived from OSCollection are retained
784 * rather than copied.
785 */
786 OSPtr<OSCollection> copyCollection(OSDictionary *cycleDict = NULL) APPLE_KEXT_OVERRIDE;
787
788 OSMetaClassDeclareReservedUnused(OSSet, 0);
789 OSMetaClassDeclareReservedUnused(OSSet, 1);
790 OSMetaClassDeclareReservedUnused(OSSet, 2);
791 OSMetaClassDeclareReservedUnused(OSSet, 3);
792 OSMetaClassDeclareReservedUnused(OSSet, 4);
793 OSMetaClassDeclareReservedUnused(OSSet, 5);
794 OSMetaClassDeclareReservedUnused(OSSet, 6);
795 OSMetaClassDeclareReservedUnused(OSSet, 7);
796};
797
798#endif /* !_OS_OSSET_H */
799