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     @class OSCollection
  39     @abstract Abstract super class for all collections.
  40     @discussion
  41     OSCollection is the abstract super class for all OSObject derived collections and provides the necessary interfaces for managing storage space and iteration through a collection.
  42 */
  43 class OSCollection : public OSObject
  44 {
  45     friend class OSCollectionIterator;
  46
  47     OSDeclareAbstractStructors(OSCollection);
  48
  49     struct ExpansionData { };
  50
  51 protected:
  52     unsigned int updateStamp;
  53
  54 private:
  55     /* Reserved for future use.  (Internal use only)  */
  56     // ExpansionData *reserved;
  57     unsigned int fOptions;
  58
  59 protected:
  60     // Member functions used by the OSCollectionIterator class.
  61     /*
  62         @function iteratorSize
  63         @abstract A pure virtual member function to return the size of the iterator context.
  64         @result Returns an integer size for the storage space required to contain context necessary for iterating through a collection.
  65         @discussion
  66         This member function is called by an OSCollectionIterator object to allow it to allocate enough storage space for the iterator context.  This context contains the data necessary to iterate through the collection when getNextObjectForIterator() is called.
  67     */
  68     virtual unsigned int iteratorSize() const = 0;
  69     /*
  70         @function initIterator
  71         @abstract Pure virtual member function to allocate and initialize the iterator context data.
  72         @param iterator The iterator context.
  73         @result Returns true if initialization was successful, false otherwise.
  74     */
  75     virtual bool initIterator(void *iterator) const = 0;
  76     /*
  77         @function getNextObjectForIterator
  78         @abstract A pure virtual member function which returns the next member of a collection.
  79         @param iterator The iterator context.
  80         @param ret The object returned to the caller.
  81         @result Returns true if an object was found, false otherwise.
  82         @discussion
  83         This is the entry point used by an OSCollectionIterator object to advance to next object in the collection.  The iterator context is passed to the receiver to allow it to find the location of the current object and then advance the iterator context to the next object.
  84     */
  85     virtual bool getNextObjectForIterator(void *iterator, OSObject **ret) const = 0;
  86
  87     /*
  88         @function init
  89         @abstract A member function to initialize the OSCollection object.
  90         @result Returns true if an object was initialized successfully, false otherwise.
  91         @discussion
  92         This function is used to initialize state within a newly created OSCollection object.
  93     */
  94     virtual bool init();
  95
  96 public:
  97     enum {
  98         kImmutable = 0x00000001,
  99         kMASK      = (unsigned) -1
 100     };
 101
 102     /*
 103         @function haveUpdated
 104         @abstract A member function to track of all updates to the collection.
 105     */
 106     void haveUpdated();
 107
 108     /*
 109         @function getCount
 110         @abstract A pure virtual member function which returns the number of objects in the collection subclass.
 111         @results Returns the number objects in a collection.
 112      */
 113     virtual unsigned int getCount() const = 0;
 114     /*
 115         @function getCapacity
 116         @abstract A pure virtual member function which returns the storage space in the collection subclass.
 117         @results Returns the number objects in a collection.
 118      */
 119     virtual unsigned int getCapacity() const = 0;
 120     /*
 121         @function getCapacityIncrement
 122         @abstract A pure virtual member function which returns the growth factor of the collection subclass.
 123         @results Returns the size by which the collection subclass should grow.
 124      */
 125     virtual unsigned int getCapacityIncrement() const = 0;
 126     /*
 127         @function setCapacityIncrement
 128         @abstract A pure virtual member function which sets the growth factor of the collection subclass.
 129         @param increment The new size by which the capacity of the collection should grow.
 130         @results Returns the new capacity increment.
 131      */
 132     virtual unsigned int setCapacityIncrement(unsigned increment) = 0;
 133
 134     /*
 135         @function ensureCapacity
 136         @abstract A pure virtual member function which
 137         @param newCapacity
 138         @result
 139      */
 140     virtual unsigned int ensureCapacity(unsigned int newCapacity) = 0;
 141
 142     /*
 143         @function flushCollection
 144         @abstract A pure virtual member function which
 145      */
 146     virtual void flushCollection() = 0;
 147
 148     /*!
 149         @function setOptions
 150         @abstract This function is used to recursively set option bits in this collection and all child collections.
 151         @discussion setOptions is a recursive function but the OSCollection class itself does not know the structure of the particular collection.  This means that all derived classes are expected to override this method and recurse if the old value of the option was NOT set, which is why the old value is returned.  As this function is a reserved function override it is very multi purpose.  It can be used to get & set the options,
 152         @param options Set the (options & mask) bits.
 153         @param mask The mask of bits which need to be set, 0 to get the current value.
 154         @result The options before the set operation, NB setOptions(?,0) returns the current value of this collection.
 155      */
 156     OSMetaClassDeclareReservedUsed(OSCollection, 0);
 157     virtual unsigned setOptions(unsigned options, unsigned mask, void * = 0);
 158
 159     /*!
 160         @function copyCollection
 161         @abstract Do a deep copy of a collection tree.
 162         @discussion This function copies this collection and all of the contained collections recursively.  Objects that don't derive from OSContainter are NOT copied, that is objects like OSString and OSData.  To a derive from OSConnection::copyCollection some code is required to be implemented in the derived class, below is the skeleton pseudo code to copy a collection.
 163
 164 OSCollection * <MyCollection>::copyCollection(OSDictionary *inCycleDict)
 165 {
 166     bool allocDict = !cycleDict;
 167     OSCollection *ret = 0;
 168     <MyCollection> *newMyColl = 0;
 169
 170     if (allocDict)
 171         cycleDict = OSDictionary::withCapacity(16);
 172     if (!cycleDict)
 173         return 0;
 174
 175     do {
 176         // Check to see if we already have a copy of the new dictionary
 177         ret = super::copyCollection(cycleDict);
 178         if (ret)
 179             continue;
 180
 181         // Your code goes here to copy your collection,
 182         // see OSArray & OSDictionary for examples.
 183         newMyColl = <MyCollection>::with<MyCollection>(this);
 184         if (!newMyColl)
 185             continue;
 186
 187         // Insert object into cycle Dictionary
 188         cycleDict->setObject((const OSSymbol *) this, newMyColl);
 189
 190         // Duplicate any collections in us
 191         for (unsigned int i = 0; i < count; i++) {
 192             OSObject *obj = getObject(i);
 193             OSCollection *coll = OSDynamicCast(OSCollection, obj);
 194
 195             if (coll) {
 196                 OSCollection *newColl = coll->copyCollection(cycleDict);
 197                 if (!newColl)
 198                     goto abortCopy;
 199
 200                 newMyColl->replaceObject(i, newColl);
 201                 newColl->release();
 202             };
 203         };
 204
 205         ret = newMyColl;
 206         newMyColl = 0;
 207
 208     } while (false);
 209
 210 abortCopy:
 211     if (newMyColl)
 212         newMyColl->release();
 213
 214     if (allocDict)
 215         cycleDict->release();
 216
 217     return ret;
 218 }
 219
 220         @param cycleDict Is a dictionary of all of the collections that have been, to start the copy at the top level just leave this field 0.
 221         @result The newly copied collecton or 0 if insufficient memory
 222     */
 223     virtual OSCollection *copyCollection(OSDictionary *cycleDict = 0);
 224     OSMetaClassDeclareReservedUsed(OSCollection, 1);
 225
 226     OSMetaClassDeclareReservedUnused(OSCollection, 2);
 227     OSMetaClassDeclareReservedUnused(OSCollection, 3);
 228     OSMetaClassDeclareReservedUnused(OSCollection, 4);
 229     OSMetaClassDeclareReservedUnused(OSCollection, 5);
 230     OSMetaClassDeclareReservedUnused(OSCollection, 6);
 231     OSMetaClassDeclareReservedUnused(OSCollection, 7);
 232 };
 233
 234 #endif /* !_OS_OSCOLLECTION_H */