libkern/libkern/c++/OSCollectionIterator.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 /* IOCollectionIterator.h created by gvdl on Fri 1998-10-30 */
  29
  30 #ifndef _OS_OSCOLLECTIONITERATOR_H
  31 #define _OS_OSCOLLECTIONITERATOR_H
  32
  33 #include <libkern/c++/OSIterator.h>
  34
  35 class OSCollection;
  36
  37 /*!
  38  * @header
  39  *
  40  * @abstract
  41  * This header declares the OSCollectionIterator collection class.
  42  */
  43
  44
  45 /*!
  46  * @class OSCollectionIterator
  47  *
  48  * @discussion
  49  * OSCollectionIterator defines a consistent mechanism to iterate
  50  * through the objects of an OSCollection.
  51  * It expands on the basic interface of
  52  * @link //apple_ref/cpp/class/OSIterator OSIterator@/link
  53  * to allow association of an iterator with a specific collection.
  54  *
  55  * To use an OSCollectionIterator, you create it with the collection
  56  * to be iterated, then call
  57  * @link //apple_ref/cpp/class/OSIterator OSIterator@/link
  58  * as long as it returns an object:
  59  *
  60  * @textblock
  61  * <pre>
  62  *     OSCollectionIterator * iterator =
  63  *         OSCollectionIterator::withCollection(myCollection);
  64  *     OSObject * object;
  65  *     while (object = iterator->getNextObject()) {
  66  *         // do something with object
  67  *     }
  68  *     // optional
  69  *     if (!iterator->isValid()) {
  70  *         // report that collection changed during iteration
  71  *     }
  72  *     iterator->release();
  73  * </pre>
  74  * @/textblock
  75  *
  76  * Note that when iterating associative collections,
  77  * the objects returned by <code>getNextObject</code> are keys;
  78  * if you want to work with the associated values,
  79  * simply look them up in the collection with the keys.
  80  *
  81  * <b>Use Restrictions</b>
  82  *
  83  * With very few exceptions in the I/O Kit, all Libkern-based C++
  84  * classes, functions, and macros are <b>unsafe</b>
  85  * to use in a primary interrupt context.
  86  * Consult the I/O Kit documentation related to primary interrupts
  87  * for more information.
  88  *
  89  * OSCollectionIterator provides no concurrency protection.
  90  */
  91 class OSCollectionIterator : public OSIterator
  92 {
  93     OSDeclareDefaultStructors(OSCollectionIterator)
  94
  95 protected:
  96 // xx-review: Do we want to document these?
  97     const OSCollection * collection;
  98     void               * collIterator;
  99     unsigned int         initialUpdateStamp;
 100     bool                 valid;
 101
 102 public:
 103    /*!
 104     * @function withCollection
 105     *
 106     * @abstract
 107     * Creates and initializes an OSCollectionIterator
 108     * for the provided collection object.
 109     *
 110     * @param inColl  The OSCollection-derived collection object to be iteratated.
 111     *
 112     * @result
 113     * A new instance of OSCollectionIterator, or <code>NULL</code> on failure.
 114     */
 115     static OSCollectionIterator * withCollection(const OSCollection * inColl);
 116
 117
 118    /*!
 119     * @function initWithCollection
 120     *
 121     * @abstract
 122     * Initializes an OSCollectionIterator
 123     * for the provided collection object.
 124     *
 125     * @param inColl  The OSCollection-derived collection object to be iteratated.
 126     * @result
 127     * <code>true</code> if the initialization was successful,
 128     * or <code>false</code> on failure.
 129     *
 130     * @discussion
 131     * Not for general use. Use the static instance creation method
 132     * <code>@link withCollection withCollection@/link</code> instead.
 133     */
 134     virtual bool initWithCollection(const OSCollection * inColl);
 135
 136
 137    /*!
 138     * @function free
 139     *
 140     * @abstract
 141     * Releases or deallocates any resources used
 142     * by the OSCollectionIterator object.
 143     *
 144     * @discussion
 145     * This function should not be called directly;
 146     * use
 147     * <code>@link
 148     * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 149     * release@/link</code>
 150     * instead.
 151     */
 152     virtual void free();
 153
 154
 155    /*!
 156     * @function reset
 157     *
 158     * @abstract
 159     * Resets the iterator to the beginning of the collection,
 160     * as if it had just been created.
 161     */
 162     virtual void reset();
 163
 164
 165    /*!
 166     * @function isValid
 167     *
 168     * @abstract
 169     * Checks that the collection hasn't been modified during iteration.
 170     *
 171     * @return
 172     * <code>true</code> if the iterator is valid for continued use,
 173     * <code>false</code> otherwise
 174     * (typically because the iteration context has been modified).
 175     */
 176     virtual bool isValid();
 177
 178
 179    /*!
 180     * @function getNextObject
 181     *
 182     * @abstract
 183     * Advances to and returns the next object in the iteration.
 184     *
 185     * @return
 186     * The next object in the iteration context,
 187     * <code>NULL</code> if there is no next object
 188     * or if the iterator is no longer valid.
 189     *
 190     * @discussion
 191     * This function first calls
 192     * <code>@link //apple_ref/cpp/instm/OSCollectionIterator/isValid/virtualbool/()
 193     * isValid@/link</code>
 194     * and returns <code>NULL</code> if that function
 195     * returns <code>false</code>.
 196     *
 197     * Subclasses must implement this pure virtual function
 198     * to check for validity with
 199     * <code>@link
 200     * //apple_ref/cpp/instm/OSCollectionIterator/isValid/virtualbool/()
 201     * isValid@/link</code>,
 202     * and then to advance the iteration context to the next object (if any)
 203     * and return that next object, or <code>NULL</code> if there is none.
 204     */
 205     virtual OSObject * getNextObject();
 206 };
 207
 208 #endif /* !_OS_OSCOLLECTIONITERATOR_H */