libkern/libkern/c++/OSCollection.h

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