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 /* IOCollection.h created by gvdl on Thu 1998-10-22 */ 29 30 #ifndef _OS_OSCOLLECTION_H 31 #define _OS_OSCOLLECTION_H 32 33 #include <libkern/c++/OSObject.h> 34 #include <libkern/c++/OSPtr.h> 35 36 class OSDictionary; 37 class OSCollection; 38 39 typedef OSCollection* OSCollectionPtr; 40 41 // We're not necessarily in C++11 mode, so we need to disable warnings 42 // for C++11 extensions 43 #pragma clang diagnostic push 44 #pragma clang diagnostic ignored "-Wc++11-extensions" 45 46 template <typename T> 47 using OSCollectionTaggedPtr = T *; 48 49 #pragma clang diagnostic pop 50 51 52 /*! 53 * @header 54 * 55 * @abstract 56 * This header declares the OSDictionary collection class. 57 */ 58 59 60 /*! 61 * @class OSCollection 62 * 63 * @abstract 64 * The abstract superclass for Libkern collections. 65 * 66 * @discussion 67 * OSCollection is the abstract superclass 68 * for all Libkern C++ object collections. 69 * It defines the necessary interfaces for managing storage space 70 * and iterating through an arbitrary collection 71 * (see the 72 * @link //apple_ref/cpp/class/OSIterator OSIterator@/link 73 * and 74 * @link //apple_ref/cpp/class/OSCollectionIterator OSCollectionIterator@/link 75 * classes). 76 * It is up to concrete subclasses 77 * to define their specific content management functions. 78 * 79 * <b>Use Restrictions</b> 80 * 81 * With very few exceptions in the I/O Kit, all Libkern-based C++ 82 * classes, functions, and macros are <b>unsafe</b> 83 * to use in a primary interrupt context. 84 * Consult the I/O Kit documentation related to primary interrupts 85 * for more information. 86 * 87 * OSCollection provides no concurrency protection; 88 * it's up to the usage context to provide any protection necessary. 89 * Some portions of the I/O Kit, such as 90 * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link, 91 * handle synchronization via defined member functions for setting 92 * properties. 93 */ 94 class OSCollection : public OSObject 95 { 96 friend class OSCollectionIterator; 97 98 OSDeclareAbstractStructors(OSCollection); 99 100 struct ExpansionData { }; 101 102 protected: 103 /* Not to be included in headerdoc. 104 * 105 * @var updateStamp 106 * 107 * @abstract 108 * A counter for changes to the collection object. 109 * 110 * @discussion 111 * The update stamp is used primarily to track validity 112 * of iteration contexts. 113 * See @link //apple_ref/cpp/class/OSIterator OSIterator@/link and 114 * @link //apple_ref/cpp/class/OSCollectionIterator OSCollectionIterator@/link 115 * for more information. 116 */ 117 unsigned int updateStamp; 118 119 #ifdef XNU_KERNEL_PRIVATE 120 protected: 121 #else 122 private: 123 #endif /* XNU_KERNEL_PRIVATE */ 124 /* Reserved for future use. (Internal use only) */ 125 // ExpansionData * reserved; 126 unsigned int fOptions; 127 128 protected: 129 // Member functions used by the OSCollectionIterator class. 130 131 132 /*! 133 * @function iteratorSize 134 * 135 * @abstract 136 * Returns the size in bytes of a subclass's iteration context. 137 * 138 * @result 139 * The size in bytes of the iteration context 140 * needed by the subclass of OSCollection. 141 * 142 * @discussion 143 * This pure virtual member function, which subclasses must implement, 144 * is called by an 145 * @link //apple_ref/doc/class/OSCollectionIterator OSCollectionIterator@/link 146 * object so that it can allocate the storage needed 147 * for the iteration context. 148 * An iteration context contains the data necessary 149 * to iterate through the collection. 150 */ 151 virtual unsigned int iteratorSize() const = 0; 152 153 154 /*! 155 * @function initIterator 156 * 157 * @abstract 158 * Initializes the iteration context for a collection subclass. 159 * 160 * @param iterationContext The iteration context to initialize. 161 * 162 * @result 163 * <code>true</code> if initialization was successful, 164 * <code>false</code> otherwise. 165 * 166 * @discussion 167 * This pure virtual member function, which subclasses must implement, 168 * is called by an 169 * @link //apple_ref/doc/class/OSCollectionIterator OSCollectionIterator@/link 170 * object to initialize an iteration context for a collection. 171 * The collection object should interpret <code>iterationContext</code> appropriately 172 * and initialize its contents to begin an iteration. 173 * 174 * This function can be called repeatedly for a given context, 175 * whenever the iterator is reset via the 176 * @link //apple_ref/cpp/instm/OSCollectionIterator/reset/virtualvoid/() 177 * OSCollectionIterator::reset@/link 178 * function. 179 */ 180 virtual bool initIterator(void * iterationContext) const = 0; 181 182 183 /*! 184 * @function getNextObjectForIterator 185 * 186 * @abstract 187 * Returns the next member of a collection. 188 * 189 * @param iterationContext The iteration context. 190 * @param nextObject The object returned by reference to the caller. 191 * 192 * @result 193 * <code>true</code> if an object was found, <code>false</code> otherwise. 194 * 195 * @discussion 196 * This pure virtual member function, which subclasses must implement, 197 * is called by an 198 * @link //apple_ref/doc/class/OSCollectionIterator OSCollectionIterator@/link 199 * to get the next object for a given iteration context. 200 * The collection object should interpret 201 * <code>iterationContext</code> appropriately, 202 * advance the context from its current object 203 * to the next object (if it exists), 204 * return that object by reference in <code>nextObject</code>, 205 * and return <code>true</code> for the function call. 206 * If there is no next object, the collection object must return <code>false</code>. 207 * 208 * For associative collections, the object returned should be the key 209 * used to access its associated value, and not the value itself. 210 */ 211 virtual bool getNextObjectForIterator( 212 void * iterationContext, 213 OSObject ** nextObject) const = 0; 214 215 216 /*! 217 * @function init 218 * 219 * @abstract 220 * Initializes the OSCollection object. 221 * 222 * @result 223 * <code>true</code> on success, <code>false</code> otherwise. 224 * 225 * @discussion 226 * This function is used to initialize state 227 * within a newly created OSCollection object. 228 */ 229 virtual bool init() APPLE_KEXT_OVERRIDE; 230 231 public: 232 233 /*! 234 * @typedef _OSCollectionFlags 235 * 236 * @const kImmutable 237 * @discussion 238 * Used with <code>@link setOptions setOptions@/link</code> 239 * to indicate the collection's contents should 240 * or should not change. 241 * 242 * An @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link 243 * object marks collections immutable when set 244 * as properties of a registry entry that's attached to a plane. 245 * This is generally an advisory flag, used for debugging; 246 * setting it does not mean a collection will in fact 247 * disallow modifications. 248 */ 249 typedef enum { 250 kImmutable = 0x00000001, 251 kSort = 0x00000002, 252 kMASK = (unsigned) - 1 253 } _OSCollectionFlags; 254 255 // xx-review: should be protected, not public 256 257 /*! 258 * @function haveUpdated 259 * 260 * @abstract 261 * Tracks updates to the collection. 262 * 263 * @discussion 264 * Subclasses call this function <i>before</i> 265 * making any change to their contents (not after, as the name implies). 266 * Update tracking is used for collection iterators, 267 * and to enforce certain protections in the IORegistry. 268 */ 269 void haveUpdated(); 270 271 272 /*! 273 * @function getCount 274 * 275 * @abstract 276 * Returns the number of objects in the collection. 277 * 278 * @result 279 * The number of objects in the collection. 280 * 281 * @discussion 282 * Subclasses must implement this pure virtual member function. 283 */ 284 virtual unsigned int getCount() const = 0; 285 286 287 /*! 288 * @function getCapacity 289 * 290 * @abstract 291 * Returns the number of objects the collection 292 * can store without reallocating. 293 * 294 * @result 295 * The number objects the collection 296 * can store without reallocating. 297 * 298 * @discussion 299 * Subclasses must implement this pure virtual member function. 300 */ 301 virtual unsigned int getCapacity() const = 0; 302 303 304 /*! 305 * @function getCapacityIncrement 306 * 307 * @abstract 308 * Returns the storage increment of the collection. 309 * 310 * @result 311 * The storage increment of the collection. 312 * 313 * @discussion 314 * Subclasses must implement this pure virtual member function. 315 * Most collection subclasses allocate their storage 316 * in multiples of the capacity increment. 317 * 318 * See 319 * <code>@link 320 * //apple_ref/cpp/instm/OSCollection/ensureCapacity/virtualunsignedint/(unsignedint) 321 * ensureCapacity@/link</code> 322 * for how the capacity increment is used. 323 */ 324 virtual unsigned int getCapacityIncrement() const = 0; 325 326 327 /*! 328 * @function setCapacityIncrement 329 * 330 * @abstract 331 * Sets the storage increment of the collection. 332 * 333 * @result 334 * The new storage increment of the collection, 335 * which may be different from the number requested. 336 * 337 * @discussion 338 * Subclasses must implement this pure virtual member function. 339 * Most collection subclasses allocate their storage 340 * in multiples of the capacity increment. 341 * 342 * Collection subclasses should gracefully handle 343 * an <code>increment</code> of zero 344 * by applying (and returning) a positive minimum capacity. 345 * 346 * Setting the capacity increment does not trigger an immediate adjustment 347 * of a collection's storage. 348 * 349 * See 350 * @link 351 * //apple_ref/cpp/instm/OSCollection/ensureCapacity/virtualunsignedint/(unsignedint) 352 * ensureCapacity@/link 353 * for how the capacity increment is used. 354 */ 355 virtual unsigned int setCapacityIncrement(unsigned increment) = 0; 356 357 358 /*! 359 * @function ensureCapacity 360 * 361 * @abstract 362 * Ensures the collection has enough space to store 363 * the requested number of objects. 364 * 365 * @param newCapacity The total number of objects the collection 366 * should be able to store. 367 * 368 * @result 369 * The new capacity of the collection, 370 * which may be different from the number requested 371 * (if smaller, reallocation of storage failed). 372 * 373 * @discussion 374 * Subclasses implement this pure virtual member function 375 * to adjust their storage so that they can hold 376 * at least <code>newCapacity</code> objects. 377 * Libkern collections generally allocate storage 378 * in multiples of their capacity increment. 379 * 380 * Subclass methods that add objects to the collection 381 * should call this function before adding any object, 382 * and should check the return value for success. 383 * 384 * Collection subclasses may reduce their storage 385 * when the number of contained objects falls below some threshold, 386 * but no Libkern collections currently do. 387 */ 388 virtual unsigned int ensureCapacity(unsigned int newCapacity) = 0; 389 390 391 /*! 392 * @function flushCollection 393 * 394 * @abstract 395 * Empties the collection, releasing any objects retained. 396 * 397 * @discussion 398 * Subclasses implement this pure virtual member function 399 * to remove their entire contents. 400 * This must not release the collection itself. 401 */ 402 virtual void flushCollection() = 0; 403 404 405 /*! 406 * @function setOptions 407 * 408 * @abstract 409 * Recursively sets option bits in this collection 410 * and all child collections. 411 * 412 * @param options A bitfield whose values turn the options on (1) or off (0). 413 * @param mask A mask indicating which bits 414 * in <code>options</code> to change. 415 * Pass 0 to get the whole current options bitfield 416 * without changing any settings. 417 * @param context Unused. 418 * 419 * @result 420 * The options bitfield as it was before the set operation. 421 * 422 * @discussion 423 * Kernel extensions should not call this function. 424 * 425 * The only option currently in use is 426 * <code>@link //apple_ref/doc/title:econst/OSCollectionFlags/kImmutable 427 * kImmutable@/link</code>. 428 * 429 * Subclasses should override this function to recursively apply 430 * the options to their contents if the options actually change. 431 */ 432 virtual unsigned setOptions( 433 unsigned options, 434 unsigned mask, 435 void * context = NULL); 436 437 /*! 438 * @function copyCollection 439 * 440 * @abstract 441 * Creates a deep copy of a collection. 442 * 443 * @param cycleDict A dictionary of all of the collections 444 * that have been copied so far, 445 * to start the copy at the top level 446 * pass <code>NULL</code> for <code>cycleDict</code>. 447 * 448 * @result 449 * The newly copied collecton, 450 * <code>NULL</code> on failure. 451 * 452 * @discussion 453 * This function copies the collection 454 * and all of the contained collections recursively. 455 * Objects that are not derived from OSCollection are retained 456 * rather than copied. 457 * 458 * Subclasses of OSCollection must override this function 459 * to properly support deep copies. 460 */ 461 virtual OSPtr<OSCollection> copyCollection(OSDictionary * cycleDict = NULL); 462 463 /*! 464 * @function iterateObjects 465 * 466 * @abstract 467 * Invoke a callback for each member of the collection. 468 * 469 * @param refcon A reference constant for the callback. 470 * @param callback The callback function, 471 * called with the refcon and each member object 472 * of the collection in turn, on the callers thread. 473 * The callback should return true to early terminate 474 * the iteration, false otherwise. 475 * 476 * @result 477 * False if the collection iteration was made invalid 478 * (see OSCollectionIterator::isValid()) otherwise true. 479 */ 480 bool iterateObjects(void * refcon, bool (*callback)(void * refcon, OSObject * object)); 481 482 #ifdef __BLOCKS__ 483 484 /*! 485 * @function iterateObjects 486 * 487 * @abstract 488 * Invoke a block for each member of the collection. 489 * 490 * @param block The block, 491 * called with the refcon and each member object 492 * of the collection in turn, on the callers thread. 493 * The block should return true to early terminate 494 * the iteration, false otherwise. 495 * 496 * @result 497 * False if the collection iteration was made invalid 498 * (see OSCollectionIterator::isValid()) otherwise true. 499 */ 500 bool iterateObjects(bool (^block)(OSObject * object)); 501 502 #endif /* __BLOCKS__ */ 503 504 OSMetaClassDeclareReservedUsedX86(OSCollection, 0); 505 OSMetaClassDeclareReservedUsedX86(OSCollection, 1); 506 OSMetaClassDeclareReservedUnused(OSCollection, 2); 507 OSMetaClassDeclareReservedUnused(OSCollection, 3); 508 OSMetaClassDeclareReservedUnused(OSCollection, 4); 509 OSMetaClassDeclareReservedUnused(OSCollection, 5); 510 OSMetaClassDeclareReservedUnused(OSCollection, 6); 511 OSMetaClassDeclareReservedUnused(OSCollection, 7); 512 }; 513 514 #endif /* !_OS_OSCOLLECTION_H */ 515