libkern/libkern/c++/OSCollectionIterator.h

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