Mac Developer Library

Developer

OSCollection Class Reference

Options
Deployment Target:

On This Page
Language:

OSCollection

The abstract superclass for Libkern collections. More...

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.0 and later.
  • Creates a deep copy of a collection.

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    virtual unsigned int ensureCapacity( unsigned intnewCapacity) = 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.

    Import Statement

  • Empties the collection, releasing any objects retained.

    Declaration

    C++

    virtual void flushCollection() = 0;

    Discussion

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

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

  • Returns the storage increment of the collection.

    Declaration

    C++

    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.

    Import Statement

  • Returns the number of objects in the collection.

    Declaration

    C++

    virtual unsigned int getCount() const = 0;

    Return Value

    The number of objects in the collection.

    Discussion

    Subclasses must implement this pure virtual member function.

    Import Statement

  • Returns the next member of a collection.

    Declaration

    C++

    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.

    Import Statement

  • Tracks updates to the collection.

    Declaration

    C++

    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.

    Import Statement

  • Initializes the OSCollection object.

    Declaration

    C++

    virtual bool init();

    Return Value

    true on success, false otherwise.

    Discussion

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

    Import Statement

  • Initializes the iteration context for a collection subclass.

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

  • Sets the storage increment of the collection.

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

Data Types

  • Declaration

    CPlusPlus

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

    Constants

    • kImmutable

      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.

    Import Statement