libkern/libkern/c++/OSCollection.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 /* IOCollection.h created by gvdl on Thu 1998-10-22 */
  29
  30 #ifndef _OS_OSCOLLECTION_H
  31 #define _OS_OSCOLLECTION_H
  32
  33 #include <libkern/c++/OSObject.h>
  34
  35 class OSDictionary;
  36
  37
  38 /*!
  39  * @header
  40  *
  41  * @abstract
  42  * This header declares the OSDictionary collection class.
  43  */
  44
  45
  46 /*!
  47  * @class OSCollection
  48  *
  49  * @abstract
  50  * The abstract superclass for Libkern collections.
  51  *
  52  * @discussion
  53  * OSCollection is the abstract superclass
  54  * for all Libkern C++ object collections.
  55  * It defines the necessary interfaces for managing storage space
  56  * and iterating through an arbitrary collection
  57  * (see the
  58  * @link //apple_ref/cpp/class/OSIterator OSIterator@/link
  59  * and
  60  * @link //apple_ref/cpp/class/OSCollectionIterator OSCollectionIterator@/link
  61  * classes).
  62  * It is up to concrete subclasses
  63  * to define their specific content management functions.
  64  *
  65  * <b>Use Restrictions</b>
  66  *
  67  * With very few exceptions in the I/O Kit, all Libkern-based C++
  68  * classes, functions, and macros are <b>unsafe</b>
  69  * to use in a primary interrupt context.
  70  * Consult the I/O Kit documentation related to primary interrupts
  71  * for more information.
  72  *
  73  * OSCollection provides no concurrency protection;
  74  * it's up to the usage context to provide any protection necessary.
  75  * Some portions of the I/O Kit, such as
  76  * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link,
  77  * handle synchronization via defined member functions for setting
  78  * properties.
  79  */
  80 class OSCollection : public OSObject
  81 {
  82     friend class OSCollectionIterator;
  83
  84     OSDeclareAbstractStructors(OSCollection);
  85
  86     struct ExpansionData { };
  87
  88 protected:
  89    /* Not to be included in headerdoc.
  90     *
  91     * @var updateStamp
  92     *
  93     * @abstract
  94     * A counter for changes to the collection object.
  95     *
  96     * @discussion
  97     * The update stamp is used primarily to track validity
  98     * of iteration contexts.
  99     * See @link //apple_ref/cpp/class/OSIterator OSIterator@/link and
 100     * @link //apple_ref/cpp/class/OSCollectionIterator OSCollectionIterator@/link
 101     * for more information.
 102     */
 103     unsigned int updateStamp;
 104
 105 private:
 106     /* Reserved for future use.  (Internal use only)  */
 107     // ExpansionData * reserved;
 108     unsigned int fOptions;
 109
 110 protected:
 111     // Member functions used by the OSCollectionIterator class.
 112
 113
 114    /*!
 115     * @function iteratorSize
 116     *
 117     * @abstract
 118     * Returns the size in bytes of a subclass's iteration context.
 119     *
 120     * @result
 121     * The size in bytes of the iteration context
 122     * needed by the subclass of OSCollection.
 123     *
 124     * @discussion
 125     * This pure virtual member function, which subclasses must implement,
 126     * is called by an
 127     * @link //apple_ref/doc/class/OSCollectionIterator OSCollectionIterator@/link
 128     * object so that it can allocate the storage needed
 129     * for the iteration context.
 130     * An iteration context contains the data necessary
 131     * to iterate through the collection.
 132     */
 133     virtual unsigned int iteratorSize() const = 0;
 134
 135
 136    /*!
 137     * @function initIterator
 138     *
 139     * @abstract
 140     * Initializes the iteration context for a collection subclass.
 141     *
 142     * @param iterationContext  The iteration context to initialize.
 143     *
 144     * @result
 145     * <code>true</code> if initialization was successful,
 146     * <code>false</code> otherwise.
 147     *
 148     * @discussion
 149     * This pure virtual member function, which subclasses must implement,
 150     * is called by an
 151     * @link //apple_ref/doc/class/OSCollectionIterator OSCollectionIterator@/link
 152     * object to initialize an iteration context for a collection.
 153     * The collection object should interpret <code>iterationContext</code> appropriately
 154     * and initialize its contents to begin an iteration.
 155     *
 156     * This function can be called repeatedly for a given context,
 157     * whenever the iterator is reset via the
 158     * @link //apple_ref/cpp/instm/OSCollectionIterator/reset/virtualvoid/()
 159     * OSCollectionIterator::reset@/link
 160     * function.
 161     */
 162     virtual bool initIterator(void * iterationContext) const = 0;
 163
 164
 165    /*!
 166     * @function getNextObjectForIterator
 167     *
 168     * @abstract
 169     * Returns the next member of a collection.
 170     *
 171     * @param iterationContext  The iteration context.
 172     * @param nextObject        The object returned by reference to the caller.
 173     *
 174     * @result
 175     * <code>true</code> if an object was found, <code>false</code> otherwise.
 176     *
 177     * @discussion
 178     * This pure virtual member function, which subclasses must implement,
 179     * is called by an
 180     * @link //apple_ref/doc/class/OSCollectionIterator OSCollectionIterator@/link
 181     * to get the next object for a given iteration context.
 182     * The collection object should interpret
 183     * <code>iterationContext</code> appropriately,
 184     * advance the context from its current object
 185     * to the next object (if it exists),
 186     * return that object by reference in <code>nextObject</code>,
 187     * and return <code>true</code> for the function call.
 188     * If there is no next object, the collection object must return <code>false</code>.
 189     *
 190     * For associative collections, the object returned should be the key
 191     * used to access its associated value, and not the value itself.
 192     */
 193     virtual bool getNextObjectForIterator(
 194         void      * iterationContext,
 195         OSObject ** nextObject) const = 0;
 196
 197
 198    /*!
 199     * @function init
 200     *
 201     * @abstract
 202     * Initializes the OSCollection object.
 203     *
 204     * @result
 205     * <code>true</code> on success, <code>false</code> otherwise.
 206     *
 207     * @discussion
 208     * This function is used to initialize state
 209     * within a newly created OSCollection object.
 210     */
 211     virtual bool init();
 212
 213 public:
 214
 215    /*!
 216     * @typedef _OSCollectionFlags
 217     *
 218     * @const kImmutable
 219     * @discussion
 220     * Used with <code>@link setOptions setOptions@/link</code>
 221     * to indicate the collection's contents should
 222     * or should not change.
 223     *
 224     * An @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link
 225     * object marks collections immutable when set
 226     * as properties of a registry entry that's attached to a plane.
 227     * This is generally an advisory flag, used for debugging;
 228     * setting it does not mean a collection will in fact
 229     * disallow modifications.
 230     */
 231     typedef enum {
 232         kImmutable  = 0x00000001,
 233         kMASK       = (unsigned) -1
 234     } _OSCollectionFlags;
 235
 236 // xx-review: should be protected, not public
 237
 238    /*!
 239     * @function haveUpdated
 240     *
 241     * @abstract
 242     * Tracks updates to the collection.
 243     *
 244     * @discussion
 245     * Subclasses call this function <i>before</i>
 246     * making any change to their contents (not after, as the name implies).
 247     * Update tracking is used for collection iterators,
 248     * and to enforce certain protections in the IORegistry.
 249     */
 250     void haveUpdated();
 251
 252
 253    /*!
 254     * @function getCount
 255     *
 256     * @abstract
 257     * Returns the number of objects in the collection.
 258     *
 259     * @result
 260     * The number of objects in the collection.
 261     *
 262     * @discussion
 263     * Subclasses must implement this pure virtual member function.
 264     */
 265     virtual unsigned int getCount() const = 0;
 266
 267
 268    /*!
 269     * @function getCapacity
 270     *
 271     * @abstract
 272     * Returns the number of objects the collection
 273     * can store without reallocating.
 274     *
 275     * @result
 276     * The number objects the collection
 277     * can store without reallocating.
 278     *
 279     * @discussion
 280     * Subclasses must implement this pure virtual member function.
 281     */
 282     virtual unsigned int getCapacity() const = 0;
 283
 284
 285    /*!
 286     * @function getCapacityIncrement
 287     *
 288     * @abstract
 289     * Returns the storage increment of the collection.
 290     *
 291     * @result
 292     * The storage increment of the collection.
 293     *
 294     * @discussion
 295     * Subclasses must implement this pure virtual member function.
 296     * Most collection subclasses allocate their storage
 297     * in multiples of the capacity increment.
 298     *
 299     * See
 300     * <code>@link
 301     * //apple_ref/cpp/instm/OSCollection/ensureCapacity/virtualunsignedint/(unsignedint)
 302     * ensureCapacity@/link</code>
 303     * for how the capacity increment is used.
 304     */
 305     virtual unsigned int getCapacityIncrement() const = 0;
 306
 307
 308    /*!
 309     * @function setCapacityIncrement
 310     *
 311     * @abstract
 312     * Sets the storage increment of the collection.
 313     *
 314     * @result
 315     * The new storage increment of the collection,
 316     * which may be different from the number requested.
 317     *
 318     * @discussion
 319     * Subclasses must implement this pure virtual member function.
 320     * Most collection subclasses allocate their storage
 321     * in multiples of the capacity increment.
 322     *
 323     * Collection subclasses should gracefully handle
 324     * an <code>increment</code> of zero
 325     * by applying (and returning) a positive minimum capacity.
 326     *
 327     * Setting the capacity increment does not trigger an immediate adjustment
 328     * of a collection's storage.
 329     *
 330     * See
 331     * @link
 332     * //apple_ref/cpp/instm/OSCollection/ensureCapacity/virtualunsignedint/(unsignedint)
 333     * ensureCapacity@/link
 334     * for how the capacity increment is used.
 335     */
 336     virtual unsigned int setCapacityIncrement(unsigned increment) = 0;
 337
 338
 339    /*!
 340     * @function ensureCapacity
 341     *
 342     * @abstract
 343     * Ensures the collection has enough space to store
 344     * the requested number of objects.
 345     *
 346     * @param newCapacity  The total number of objects the collection
 347     *                     should be able to store.
 348     *
 349     * @result
 350     * The new capacity of the collection,
 351     * which may be different from the number requested
 352     * (if smaller, reallocation of storage failed).
 353     *
 354     * @discussion
 355     * Subclasses implement this pure virtual member function
 356     * to adjust their storage so that they can hold
 357     * at least <code>newCapacity</code> objects.
 358     * Libkern collections generally allocate storage
 359     * in multiples of their capacity increment.
 360     *
 361     * Subclass methods that add objects to the collection
 362     * should call this function before adding any object,
 363     * and should check the return value for success.
 364     *
 365     * Collection subclasses may reduce their storage
 366     * when the number of contained objects falls below some threshold,
 367     * but no Libkern collections currently do.
 368     */
 369     virtual unsigned int ensureCapacity(unsigned int newCapacity) = 0;
 370
 371
 372    /*!
 373     * @function flushCollection
 374     *
 375     * @abstract
 376     * Empties the collection, releasing any objects retained.
 377     *
 378     * @discussion
 379     * Subclasses implement this pure virtual member function
 380     * to remove their entire contents.
 381     * This must not release the collection itself.
 382     */
 383     virtual void flushCollection() = 0;
 384
 385
 386    /*!
 387     * @function setOptions
 388     *
 389     * @abstract
 390     * Recursively sets option bits in this collection
 391     * and all child collections.
 392     *
 393     * @param options  A bitfield whose values turn the options on (1) or off (0).
 394     * @param mask     A mask indicating which bits
 395     *                 in <code>options</code> to change.
 396     *                 Pass 0 to get the whole current options bitfield
 397     *                 without changing any settings.
 398     * @param context  Unused.
 399     *
 400     * @result
 401     * The options bitfield as it was before the set operation.
 402     *
 403     * @discussion
 404     * Kernel extensions should not call this function.
 405     *
 406     * The only option currently in use is
 407     * <code>@link //apple_ref/doc/title:econst/OSCollectionFlags/kImmutable
 408     * kImmutable@/link</code>.
 409     *
 410     * Subclasses should override this function to recursively apply
 411     * the options to their contents if the options actually change.
 412     */
 413     virtual unsigned setOptions(
 414         unsigned   options,
 415         unsigned   mask,
 416         void     * context = 0);
 417     OSMetaClassDeclareReservedUsed(OSCollection, 0);
 418
 419    /*!
 420     * @function copyCollection
 421     *
 422     * @abstract
 423     * Creates a deep copy of a collection.
 424     *
 425     * @param cycleDict  A dictionary of all of the collections
 426     *                   that have been copied so far,
 427     *                   to start the copy at the top level
 428     *                   pass <code>NULL</code> for <code>cycleDict</code>.
 429     *
 430     * @result
 431     * The newly copied collecton,
 432     * <code>NULL</code> on failure.
 433     *
 434     * @discussion
 435     * This function copies the collection
 436     * and all of the contained collections recursively.
 437     * Objects that are not derived from OSCollection are retained
 438     * rather than copied.
 439     *
 440     * Subclasses of OSCollection must override this function
 441     * to properly support deep copies.
 442     */
 443     virtual OSCollection *copyCollection(OSDictionary * cycleDict = 0);
 444     OSMetaClassDeclareReservedUsed(OSCollection, 1);
 445
 446
 447     OSMetaClassDeclareReservedUnused(OSCollection, 2);
 448     OSMetaClassDeclareReservedUnused(OSCollection, 3);
 449     OSMetaClassDeclareReservedUnused(OSCollection, 4);
 450     OSMetaClassDeclareReservedUnused(OSCollection, 5);
 451     OSMetaClassDeclareReservedUnused(OSCollection, 6);
 452     OSMetaClassDeclareReservedUnused(OSCollection, 7);
 453 };
 454
 455 #endif /* !_OS_OSCOLLECTION_H */