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