OSCollection

Inherits from
OSObject
Availability
Available in OS X v10.0 and later.
Declared in
OSCollection.h

Overview

The abstract superclass for Libkern collections.

OSCollection is the abstract superclass for all Libkern C++ object collections. It defines the necessary interfaces for managing storage space and iterating through an arbitrary collection (see the OSIterator and OSCollectionIterator classes). It is up to concrete subclasses to define their specific content management functions.

Use Restrictions

With very few exceptions in the I/O Kit, all Libkern-based C++ classes, functions, and macros are unsafe to use in a primary interrupt context. Consult the I/O Kit documentation related to primary interrupts for more information.

OSCollection provides no concurrency protection; it's up to the usage context to provide any protection necessary. Some portions of the I/O Kit, such as IORegistryEntry, handle synchronization via defined member functions for setting properties.

Tasks

Miscellaneous

Instance Methods

copyCollection

Creates a deep copy of a collection.

virtual OSCollection *copyCollection( OSDictionary *cycleDict = 0);
Parameters
cycleDict

A dictionary of all of the collections that have been copied so far, to start the copy at the top level pass NULL for cycleDict.

Return Value

The newly copied collecton, NULL on failure.

Discussion

This function copies the collection and all of the contained collections recursively. Objects that are not derived from OSCollection are retained rather than copied.

Subclasses of OSCollection must override this function to properly support deep copies.

ensureCapacity

Ensures the collection has enough space to store the requested number of objects.

virtual unsigned int ensureCapacity( unsigned int newCapacity) = 0;
Parameters
newCapacity

The total number of objects the collection should be able to store.

Return Value

The new capacity of the collection, which may be different from the number requested (if smaller, reallocation of storage failed).

Discussion

Subclasses implement this pure virtual member function to adjust their storage so that they can hold at least newCapacity objects. Libkern collections generally allocate storage in multiples of their capacity increment.

Subclass methods that add objects to the collection should call this function before adding any object, and should check the return value for success.

Collection subclasses may reduce their storage when the number of contained objects falls below some threshold, but no Libkern collections currently do.

flushCollection

Empties the collection, releasing any objects retained.

virtual void flushCollection() = 0;
Discussion

Subclasses implement this pure virtual member function to remove their entire contents. This must not release the collection itself.

getCapacity

Returns the number of objects the collection can store without reallocating.

virtual unsigned int getCapacity() const = 0;
Return Value

The number objects the collection can store without reallocating.

Discussion

Subclasses must implement this pure virtual member function.

getCapacityIncrement

Returns the storage increment of the collection.

virtual unsigned int getCapacityIncrement() const = 0;
Return Value

The storage increment of the collection.

Discussion

Subclasses must implement this pure virtual member function. Most collection subclasses allocate their storage in multiples of the capacity increment.

See ensureCapacity for how the capacity increment is used.

getCount

Returns the number of objects in the collection.

virtual unsigned int getCount() const = 0;
Return Value

The number of objects in the collection.

Discussion

Subclasses must implement this pure virtual member function.

getNextObjectForIterator

Returns the next member of a collection.

virtual bool getNextObjectForIterator( void *iterationContext, OSObject **nextObject) const = 0;
Parameters
iterationContext

The iteration context.

nextObject

The object returned by reference to the caller.

Return Value

true if an object was found, false otherwise.

Discussion

This pure virtual member function, which subclasses must implement, is called by an OSCollectionIterator to get the next object for a given iteration context. The collection object should interpret iterationContext appropriately, advance the context from its current object to the next object (if it exists), return that object by reference in nextObject, and return true for the function call. If there is no next object, the collection object must return false.

For associative collections, the object returned should be the key used to access its associated value, and not the value itself.

haveUpdated

Tracks updates to the collection.

void haveUpdated();
Discussion

Subclasses call this function before making any change to their contents (not after, as the name implies). Update tracking is used for collection iterators, and to enforce certain protections in the IORegistry.

init

Initializes the OSCollection object.

virtual bool init();
Return Value

true on success, false otherwise.

Discussion

This function is used to initialize state within a newly created OSCollection object.

initIterator

Initializes the iteration context for a collection subclass.

virtual bool initIterator( void *iterationContext) const = 0;
Parameters
iterationContext

The iteration context to initialize.

Return Value

true if initialization was successful, false otherwise.

Discussion

This pure virtual member function, which subclasses must implement, is called by an OSCollectionIterator object to initialize an iteration context for a collection. The collection object should interpret iterationContext appropriately and initialize its contents to begin an iteration.

This function can be called repeatedly for a given context, whenever the iterator is reset via the OSCollectionIterator::reset function.

iteratorSize

Returns the size in bytes of a subclass's iteration context.

virtual unsigned int iteratorSize() const = 0;
Return Value

The size in bytes of the iteration context needed by the subclass of OSCollection.

Discussion

This pure virtual member function, which subclasses must implement, is called by an OSCollectionIterator object so that it can allocate the storage needed for the iteration context. An iteration context contains the data necessary to iterate through the collection.

setCapacityIncrement

Sets the storage increment of the collection.

virtual unsigned int setCapacityIncrement( unsigned increment) = 0;
Return Value

The new storage increment of the collection, which may be different from the number requested.

Discussion

Subclasses must implement this pure virtual member function. Most collection subclasses allocate their storage in multiples of the capacity increment.

Collection subclasses should gracefully handle an increment of zero by applying (and returning) a positive minimum capacity.

Setting the capacity increment does not trigger an immediate adjustment of a collection's storage.

See ensureCapacity for how the capacity increment is used.

setOptions

Recursively sets option bits in this collection and all child collections.

virtual unsigned setOptions( unsigned options, unsigned mask, void *context = 0);
Parameters
options

A bitfield whose values turn the options on (1) or off (0).

mask

A mask indicating which bits in options to change. Pass 0 to get the whole current options bitfield without changing any settings.

context

Unused.

Return Value

The options bitfield as it was before the set operation.

Discussion

Kernel extensions should not call this function.

The only option currently in use is kImmutable.

Subclasses should override this function to recursively apply the options to their contents if the options actually change.

_OSCollectionFlags

typedef enum {
   kImmutable = 0x00000001,
   kSort = 0x00000002,
   kMASK = (
   unsigned) -1
} _OSCollectionFlags;
Constants
kImmutable
Discussion

Used with setOptions to indicate the collection's contents should or should not change.

An IORegistryEntry object marks collections immutable when set as properties of a registry entry that's attached to a plane. This is generally an advisory flag, used for debugging; setting it does not mean a collection will in fact disallow modifications.