libkern/libkern/c++/OSCollection.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_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
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30 /* IOCollection.h created by gvdl on Thu 1998-10-22 */
  31
  32 #ifndef _OS_OSCOLLECTION_H
  33 #define _OS_OSCOLLECTION_H
  34
  35 #include <libkern/c++/OSObject.h>
  36
  37 class OSDictionary;
  38
  39 /*!
  40     @class OSCollection
  41     @abstract Abstract super class for all collections.
  42     @discussion
  43     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.
  44 */
  45 class OSCollection : public OSObject
  46 {
  47     friend class OSCollectionIterator;
  48
  49     OSDeclareAbstractStructors(OSCollection);
  50
  51     struct ExpansionData { };
  52
  53 protected:
  54     unsigned int updateStamp;
  55
  56 private:
  57     /* Reserved for future use.  (Internal use only)  */
  58     // ExpansionData *reserved;
  59     unsigned int fOptions;
  60
  61 protected:
  62     // Member functions used by the OSCollectionIterator class.
  63     /*
  64         @function iteratorSize
  65         @abstract A pure virtual member function to return the size of the iterator context.
  66         @result Returns an integer size for the storage space required to contain context necessary for iterating through a collection.
  67         @discussion
  68         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.
  69     */
  70     virtual unsigned int iteratorSize() const = 0;
  71     /*
  72         @function initIterator
  73         @abstract Pure virtual member function to allocate and initialize the iterator context data.
  74         @param iterator The iterator context.
  75         @result Returns true if initialization was successful, false otherwise.
  76     */
  77     virtual bool initIterator(void *iterator) const = 0;
  78     /*
  79         @function getNextObjectForIterator
  80         @abstract A pure virtual member function which returns the next member of a collection.
  81         @param iterator The iterator context.
  82         @param ret The object returned to the caller.
  83         @result Returns true if an object was found, false otherwise.
  84         @discussion
  85         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.
  86     */
  87     virtual bool getNextObjectForIterator(void *iterator, OSObject **ret) const = 0;
  88
  89     /*
  90         @function init
  91         @abstract A member function to initialize the OSCollection object.
  92         @result Returns true if an object was initialized successfully, false otherwise.
  93         @discussion
  94         This function is used to initialize state within a newly created OSCollection object.
  95     */
  96     virtual bool init();
  97
  98 public:
  99     enum {
 100         kImmutable = 0x00000001,
 101         kMASK      = (unsigned) -1
 102     };
 103
 104     /*
 105         @function haveUpdated
 106         @abstract A member function to track of all updates to the collection.
 107     */
 108     void haveUpdated();
 109
 110     /*
 111         @function getCount
 112         @abstract A pure virtual member function which returns the number of objects in the collection subclass.
 113         @results Returns the number objects in a collection.
 114      */
 115     virtual unsigned int getCount() const = 0;
 116     /*
 117         @function getCapacity
 118         @abstract A pure virtual member function which returns the storage space in the collection subclass.
 119         @results Returns the number objects in a collection.
 120      */
 121     virtual unsigned int getCapacity() const = 0;
 122     /*
 123         @function getCapacityIncrement
 124         @abstract A pure virtual member function which returns the growth factor of the collection subclass.
 125         @results Returns the size by which the collection subclass should grow.
 126      */
 127     virtual unsigned int getCapacityIncrement() const = 0;
 128     /*
 129         @function setCapacityIncrement
 130         @abstract A pure virtual member function which sets the growth factor of the collection subclass.
 131         @param increment The new size by which the capacity of the collection should grow.
 132         @results Returns the new capacity increment.
 133      */
 134     virtual unsigned int setCapacityIncrement(unsigned increment) = 0;
 135
 136     /*
 137         @function ensureCapacity
 138         @abstract A pure virtual member function which
 139         @param newCapacity
 140         @result
 141      */
 142     virtual unsigned int ensureCapacity(unsigned int newCapacity) = 0;
 143
 144     /*
 145         @function flushCollection
 146         @abstract A pure virtual member function which
 147      */
 148     virtual void flushCollection() = 0;
 149
 150     /*!
 151         @function setOptions
 152         @abstract This function is used to recursively set option bits in this collection and all child collections.
 153         @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,
 154         @param options Set the (options & mask) bits.
 155         @param mask The mask of bits which need to be set, 0 to get the current value.
 156         @result The options before the set operation, NB setOptions(?,0) returns the current value of this collection.
 157      */
 158     OSMetaClassDeclareReservedUsed(OSCollection, 0);
 159     virtual unsigned setOptions(unsigned options, unsigned mask, void * = 0);
 160
 161     /*!
 162         @function copyCollection
 163         @abstract Do a deep copy of a collection tree.
 164         @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.
 165
 166 OSCollection * <MyCollection>::copyCollection(OSDictionary *inCycleDict)
 167 {
 168     bool allocDict = !cycleDict;
 169     OSCollection *ret = 0;
 170     <MyCollection> *newMyColl = 0;
 171
 172     if (allocDict)
 173         cycleDict = OSDictionary::withCapacity(16);
 174     if (!cycleDict)
 175         return 0;
 176
 177     do {
 178         // Check to see if we already have a copy of the new dictionary
 179         ret = super::copyCollection(cycleDict);
 180         if (ret)
 181             continue;
 182
 183         // Your code goes here to copy your collection,
 184         // see OSArray & OSDictionary for examples.
 185         newMyColl = <MyCollection>::with<MyCollection>(this);
 186         if (!newMyColl)
 187             continue;
 188
 189         // Insert object into cycle Dictionary
 190         cycleDict->setObject((const OSSymbol *) this, newMyColl);
 191
 192         // Duplicate any collections in us
 193         for (unsigned int i = 0; i < count; i++) {
 194             OSObject *obj = getObject(i);
 195             OSCollection *coll = OSDynamicCast(OSCollection, obj);
 196
 197             if (coll) {
 198                 OSCollection *newColl = coll->copyCollection(cycleDict);
 199                 if (!newColl)
 200                     goto abortCopy;
 201
 202                 newMyColl->replaceObject(i, newColl);
 203                 newColl->release();
 204             };
 205         };
 206
 207         ret = newMyColl;
 208         newMyColl = 0;
 209
 210     } while (false);
 211
 212 abortCopy:
 213     if (newMyColl)
 214         newMyColl->release();
 215
 216     if (allocDict)
 217         cycleDict->release();
 218
 219     return ret;
 220 }
 221
 222         @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.
 223         @result The newly copied collecton or 0 if insufficient memory
 224     */
 225     virtual OSCollection *copyCollection(OSDictionary *cycleDict = 0);
 226     OSMetaClassDeclareReservedUsed(OSCollection, 1);
 227
 228     OSMetaClassDeclareReservedUnused(OSCollection, 2);
 229     OSMetaClassDeclareReservedUnused(OSCollection, 3);
 230     OSMetaClassDeclareReservedUnused(OSCollection, 4);
 231     OSMetaClassDeclareReservedUnused(OSCollection, 5);
 232     OSMetaClassDeclareReservedUnused(OSCollection, 6);
 233     OSMetaClassDeclareReservedUnused(OSCollection, 7);
 234 };
 235
 236 #endif /* !_OS_OSCOLLECTION_H */