libkern/libkern/c++/OSSet.h

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