OSCollection

Overview

The abstract superclass for Libkern collections.

Discussion

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.

Functions

copyCollection

Creates a deep copy of a collection.

ensureCapacity

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

flushCollection

Empties the collection, releasing any objects retained.

getCapacity

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

getCapacityIncrement

Returns the storage increment of the collection.

getCount

Returns the number of objects in the collection.

getNextObjectForIterator

Returns the next member of a collection.

haveUpdated

Tracks updates to the collection.

init

Initializes the OSCollection object.

initIterator

Initializes the iteration context for a collection subclass.

iteratorSize

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

setCapacityIncrement

Sets the storage increment of the collection.

setOptions

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

Creates a deep copy of a collection.

public

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

Parameters

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.

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

public

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

Parameters

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.

Empties the collection, releasing any objects retained.

public

virtual void flushCollection() = 0; 

Discussion

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

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

public

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.

Returns the storage increment of the collection.

public

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.

Returns the number of objects in the collection.

public

virtual unsigned int getCount() const = 0; 

Return Value

The number of objects in the collection.

Discussion

Subclasses must implement this pure virtual member function.

Returns the next member of a collection.

protected

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

Parameters

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.

Tracks updates to the collection.

public

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.

Initializes the OSCollection object.

protected

virtual bool init(); 

Return Value

true on success, false otherwise.

Discussion

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

Initializes the iteration context for a collection subclass.

protected

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

Parameters

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.

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

protected

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.

Sets the storage increment of the collection.

public

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.

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

public

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

Parameters

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.

Typedefs

_OSCollectionFlags

public

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

Constants

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.

Last Updated: 2009-10-14