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 36 class OSOffset; 37 class OSOrderedSet; 38 39 typedef 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 */ 99 class OSOrderedSet : public OSCollection 100 { 101 OSDeclareDefaultStructors(OSOrderedSet); 102 103 public: 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 130 protected: 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 143 protected: 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 149 public: 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