libkern/libkern/c++/OSCollection.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /* IOCollection.h created by gvdl on Thu 1998-10-22 */
  23
  24 #ifndef _OS_OSCOLLECTION_H
  25 #define _OS_OSCOLLECTION_H
  26
  27 #include <libkern/c++/OSObject.h>
  28
  29 /*!
  30     @class OSCollection
  31     @abstract Abstract super class for all collections.
  32     @discussion
  33     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.
  34 */
  35 class OSCollection : public OSObject
  36 {
  37     friend class OSCollectionIterator;
  38
  39     OSDeclareAbstractStructors(OSCollection)
  40
  41 protected:
  42     unsigned int updateStamp;
  43
  44     struct ExpansionData { };
  45
  46     /*! @var reserved
  47         Reserved for future use.  (Internal use only)  */
  48     ExpansionData *reserved;
  49
  50     // Member functions used by the OSCollectionIterator class.
  51     /*
  52         @function iteratorSize
  53         @abstract A pure virtual member function to return the size of the iterator context.
  54         @result Returns an integer size for the storage space required to contain context necessary for iterating through a collection.
  55         @discussion
  56         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.
  57     */
  58     virtual unsigned int iteratorSize() const = 0;
  59     /*
  60         @function initIterator
  61         @abstract Pure virtual member function to allocate and initialize the iterator context data.
  62         @param iterator The iterator context.
  63         @result Returns true if initialization was successful, false otherwise.
  64     */
  65     virtual bool initIterator(void *iterator) const = 0;
  66     /*
  67         @function getNextObjectForIterator
  68         @abstract A pure virtual member function which returns the next member of a collection.
  69         @param iterator The iterator context.
  70         @param ret The object returned to the caller.
  71         @result Returns true if an object was found, false otherwise.
  72         @discussion
  73         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.
  74     */
  75     virtual bool getNextObjectForIterator(void *iterator, OSObject **ret) const = 0;
  76
  77     /*
  78         @function init
  79         @abstract A member function to initialize the OSCollection object.
  80         @result Returns true if an object was initialized successfully, false otherwise.
  81         @discussion
  82         This function is used to initialize state within a newly created OSCollection object.
  83     */
  84     virtual bool init();
  85
  86 public:
  87     /*
  88         @function haveUpdated
  89         @abstract A member function to track of all updates to the collection.
  90     */
  91     void haveUpdated() { updateStamp++; };
  92
  93     /*
  94         @function getCount
  95         @abstract A pure virtual member function which returns the number of objects in the collection subclass.
  96         @results Returns the number objects in a collection.
  97      */
  98     virtual unsigned int getCount() const = 0;
  99     /*
 100         @function getCapacity
 101         @abstract A pure virtual member function which returns the storage space in the collection subclass.
 102         @results Returns the number objects in a collection.
 103      */
 104     virtual unsigned int getCapacity() const = 0;
 105     /*
 106         @function getCapacityIncrement
 107         @abstract A pure virtual member function which returns the growth factor of the collection subclass.
 108         @results Returns the size by which the collection subclass should grow.
 109      */
 110     virtual unsigned int getCapacityIncrement() const = 0;
 111     /*
 112         @function setCapacityIncrement
 113         @abstract A pure virtual member function which sets the growth factor of the collection subclass.
 114         @param increment The new size by which the capacity of the collection should grow.
 115         @results Returns the new capacity increment.
 116      */
 117     virtual unsigned int setCapacityIncrement(unsigned increment) = 0;
 118
 119     /*
 120         @function ensureCapacity
 121         @abstract A pure virtual member function which
 122         @param newCapacity
 123         @result
 124      */
 125     virtual unsigned int ensureCapacity(unsigned int newCapacity) = 0;
 126
 127     /*
 128         @function flushCollection
 129         @abstract A pure virtual member function which
 130      */
 131     virtual void flushCollection() = 0;
 132
 133     OSMetaClassDeclareReservedUnused(OSCollection, 0);
 134     OSMetaClassDeclareReservedUnused(OSCollection, 1);
 135     OSMetaClassDeclareReservedUnused(OSCollection, 2);
 136     OSMetaClassDeclareReservedUnused(OSCollection, 3);
 137     OSMetaClassDeclareReservedUnused(OSCollection, 4);
 138     OSMetaClassDeclareReservedUnused(OSCollection, 5);
 139     OSMetaClassDeclareReservedUnused(OSCollection, 6);
 140     OSMetaClassDeclareReservedUnused(OSCollection, 7);
 141 };
 142
 143 #endif /* !_OS_OSCOLLECTION_H */