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