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