Mac Developer Library

Developer

OSSet Class Reference

Options
Deployment Target:

On This Page
Language:

OSSet

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

OSSet provides an unordered set store of objects.

OSSet is a container for Libkern C++ objects (those derived from OSMetaClassBase, in particular OSObject). Storage and access follow basic set logic: you can add or remove an object, and test whether the set contains a particular object. A given object is only stored in the set once, and there is no ordering of objects in the set. A subclass OSOrderedSet, provides for ordered set logic.

As with all Libkern collection classes, OSSet retains objects added to it, and releases objects removed from it. An OSSet also grows as necessary to accommodate new objects, unlike Core Foundation collections (it does not, however, shrink).

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.

OSSet 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.

  • Checks the set for the presence of an object.

    Declaration

    C++

    virtual bool containsObject( const OSMetaClassBase *anObject) const;

    Parameters

    anObject

    The OSMetaClassBase-derived object to check for in the set.

    Return Value

    true if anObject is present within the set, false otherwise.

    Discussion

    Pointer equality is used. This function returns false if passed NULL.

  • Creates a deep copy of this set and its child collections.

    Declaration

    C++

    OSCollection *copyCollection( OSDictionary *cycleDict = 0);

    Parameters

    cycleDict

    A dictionary of all of the collections that have been copied so far, which is used to track circular references. To start the copy at the top level, pass NULL.

    Return Value

    The newly copied set, with a retain count of 1, or NULL if there is insufficient memory to do the copy.

    Discussion

    The receiving set, and any collections it contains, recursively, are copied. Objects that are not derived from OSCollection are retained rather than copied.

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

    Declaration

    C++

    virtual unsigned int ensureCapacity( unsigned intnewCapacity);

    Parameters

    newCapacity

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

    Return Value

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

    Discussion

    This function immediately resizes the set, if necessary, to accommodate at least newCapacity distinct objects. If newCapacity is not greater than the current capacity, or if an allocation error occurs, the original capacity is returned.

    There is no way to reduce the capacity of an OSSet.

  • Removes and releases all objects within the set.

    Declaration

    C++

    virtual void flushCollection();

    Discussion

    The set's capacity (and therefore direct memory consumption) is not reduced by this function.

  • Deallocates or releases any resources used by the OSSet instance.

    Declaration

    C++

    virtual void free();

    Discussion

    This function should not be called directly; use release instead.

  • Returns an arbitrary (not random) object from the set.

    Declaration

    C++

    virtual OSObject * getAnyObject() const;

    Return Value

    An arbitrary (not random) object if one exists within the set.

    Discussion

    The returned object will be released if removed from the set; if you plan to store the reference, you should call retain on that object.

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

    Declaration

    C++

    virtual unsigned int getCapacity() const;

    Return Value

    The number objects the set can store without reallocating.

    Discussion

    OSSet objects grow when full to accommodate additional objects. See getCapacityIncrement and ensureCapacity.

  • Returns the storage increment of the set.

    Declaration

    C++

    virtual unsigned int getCapacityIncrement() const;

    Return Value

    The storage increment of the set.

    Discussion

    An OSSet allocates storage for objects in multiples of the capacity increment.

  • Returns the current number of objects within the set.

    Declaration

    C++

    virtual unsigned int getCount() const;

    Return Value

    The current number of objects within the set.

  • Initializes a new OSSet populated with the contents of an OSArray.

    Declaration

    C++

    virtual bool initWithArray( const OSArray *array, unsigned int capacity = 0);

    Parameters

    array

    An OSAray whose contents will be placed in the new instance.

    capacity

    The initial storage capacity of the new set object. If 0, the capacity is set to the number of objects in array; otherwise capacity must be greater than or equal to the number of objects in array.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withArray instead.

    array must be non-NULL. If capacity is nonzero, it must be greater than or equal to count. The new array will grow as needed to accommodate more key-object pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).

    The objects in array are retained for storage in the new set, not copied.

  • Initializes a new instance of OSSet.

    Declaration

    C++

    virtual bool initWithCapacity( unsigned intcapacity);

    Parameters

    capacity

    The initial storage capacity of the new set object.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withCapacity instead.

    capacity must be nonzero. The new set will grow as needed to accommodate more key/object pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).

  • Initializes a new OSSet populated with objects provided.

    Declaration

    C++

    virtual bool initWithObjects( const OSObject *objects[], unsigned int count, unsigned int capacity = 0);

    Parameters

    objects

    A C array of OSObject-derived objects.

    count

    The number of objects to be placed into the set.

    capacity

    The initial storage capacity of the new set object. If 0, count is used; otherwise this value must be greater than or equal to count.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withObjects instead.

    objects must be non-NULL, and count must be nonzero. If capacity is nonzero, it must be greater than or equal to count. The new array will grow as needed to accommodate more key-object pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).

    The objects in objects are retained for storage in the new set, not copied.

  • Initializes a new OSSet populated with the contents of another OSSet.

    Declaration

    C++

    virtual bool initWithSet( const OSSet *set, unsigned int capacity = 0);

    Parameters

    set

    A set whose contents will be placed in the new instance.

    capacity

    The initial storage capacity of the new set object. If 0, the capacity is set to the number of objects in set; otherwise capacity must be greater than or equal to the number of objects in set.

    Return Value

    true on success, false on failure.

    Discussion

    Not for general use. Use the static instance creation method withSet instead.

    set must be non-NULL. If capacity is nonzero, it must be greater than or equal to count. The new set will grow as needed to accommodate more key-object pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).

    The objects in set are retained for storage in the new set, not copied.

  • Tests the equality of an OSSet against an arbitrary object.

    Declaration

    C++

    virtual bool isEqualTo( const OSMetaClassBase *anObject) const;

    Parameters

    anObject

    The object being compared against the receiver.

    Return Value

    true if the two objects are equivalent, false otherwise.

    Discussion

    An OSSet object is considered equal to another object if the other object is derived from OSSet and compares equal as a set.

  • Tests the equality of two OSSet objects.

    Declaration

    C++

    virtual bool isEqualTo( const OSSet *aSet) const;

    Parameters

    aSet

    The set object being compared against the receiver.

    Return Value

    true if the two sets are equivalent, false otherwise.

    Discussion

    Two OSSet objects are considered equal if they have same count and the same object pointer values.

  • Checks the set for the presence of an object.

    Declaration

    C++

    virtual bool member( const OSMetaClassBase *anObject) const;

    Parameters

    anObject

    The OSMetaClassBase-derived object to check for in the set.

    Return Value

    true if anObject is present within the set, false otherwise.

    Discussion

    Pointer equality is used. This function returns false if passed NULL.

    containsObject checks for NULL first, and is therefore more efficient than this function.

  • Adds the contents of an OSArray to the set.

    Declaration

    C++

    virtual bool merge( const OSArray *array);

    Parameters

    array

    The OSArray object containing the objects to be added.

    Return Value

    true if all objects from array are successfully added the receiver (or were already present), false otherwise.

    Discussion

    This functions adds to the receiving set all objects from array that are not already in the receiving set. Objects added to the receiver are retained.

    In releases prior to 10.7, this function would return false if an object from array was already present in the set, or if array was empty. This is no longer the case, so this function correctly returns true when the semantic of merging is met.

  • Adds the contents of an OSet to the set.

    Declaration

    C++

    virtual bool merge( const OSSet *set);

    Parameters

    set

    The OSSet object containing the objects to be added.

    Return Value

    true if any object from set are successfully added the receiver (or were already present), false otherwise.

    Discussion

    This functions adds to the receiving set all objects from set that are not already in the receiving set. Objects added to the receiver are retained.

    In releases prior to 10.7, this function would return false if an object from set was already present in the set, or if set was empty. This is no longer the case, so this function correctly returns true when the semantic of merging is met.

  • Removes an object from the set.

    Declaration

    C++

    virtual void removeObject( const OSMetaClassBase *anObject);

    Parameters

    anObject

    The OSMetaClassBase-derived object to be removed from the set.

    Discussion

    The object removed from the set is released.

  • Archives the receiver into the provided OSSerialize object.

    Declaration

    C++

    virtual bool serialize( OSSerialize *serializer) const;

    Parameters

    serializer

    The OSSerialize object.

    Return Value

    true if serialization succeeds, false if not.

  • Sets the storage increment of the set.

    Declaration

    C++

    virtual unsigned int setCapacityIncrement( unsigned increment);

    Return Value

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

    Discussion

    An OSSet allocates storage for objects in multiples of the capacity increment. Calling this function does not immediately reallocate storage.

  • Adds an object to the OSSet if it is not already present.

    Declaration

    C++

    virtual bool setObject( const OSMetaClassBase *anObject);

    Parameters

    anObject

    The OSMetaClassBase-derived object to be added to the set.

    Return Value

    true if anObject was successfully added to the set, false otherwise (including if it was already in the set).

    Discussion

    The set adds storage to accomodate the new object, if necessary. If successfully added, the object is retained.

    A false return value can mean either that anObject is already present in the set, or that a memory allocation failure occurred. If you need to know whether the object is already present, use containsObject.

  • Recursively sets option bits in the set 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.

    Child collections' options are changed only if the receiving set's options actually change.

  • Creates and initializes an OSSet populated with the contents of an OSArray.

    Declaration

    C++

    static OSSet * withArray( const OSArray *array, unsigned int capacity = 0);

    Parameters

    array

    An array whose objects will be stored in the new OSSet.

    capacity

    The initial storage capacity of the new set object. If 0, the capacity is set to the number of objects in array; otherwise capacity must be greater than or equal to the number of objects in array.

    Return Value

    An instance of OSSet containing the objects of array, with a retain count of 1; NULL on failure.

    Discussion

    Each distinct object in array is added to the new set.

    array must be non-NULL. If capacity is nonzero, it must be greater than or equal to count. The new OSSet will grow as needed to accommodate more key-object pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).

    The objects in array are retained for storage in the new set, not copied.

  • Creates and initializes an empty OSSet.

    Declaration

    C++

    static OSSet * withCapacity( unsigned intcapacity);

    Parameters

    capacity

    The initial storage capacity of the new set object.

    Return Value

    An empty instance of OSSet with a retain count of 1; NULL on failure.

    Discussion

    capacity must be nonzero. The new OSSet will grow as needed to accommodate more key/object pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).

  • Creates and initializes an OSSet populated with objects provided.

    Declaration

    C++

    static OSSet * withObjects( const OSObject *objects[], unsigned int count, unsigned int capacity = 0);

    Parameters

    objects

    A C array of OSMetaClassBase-derived objects.

    count

    The number of objects to be placed into the set.

    capacity

    The initial storage capacity of the new set object. If 0, count is used; otherwise this value must be greater than or equal to count.

    Return Value

    An instance of OSSet containing the objects provided, with a retain count of 1; NULL on failure.

    Discussion

    objects must be non-NULL, and count must be nonzero. If capacity is nonzero, it must be greater than or equal to count. The new OSSet will grow as needed to accommodate more objects (unlike CFMutableSet, for which the initial capacity is a hard limit).

    The objects in objects are retained for storage in the new set, not copied.

  • Creates and initializes an OSSet populated with the contents of another OSSet.

    Declaration

    C++

    static OSSet * withSet( const OSSet *set, unsigned int capacity = 0);

    Parameters

    set

    An OSSet whose contents will be stored in the new instance.

    capacity

    The initial storage capacity of the set object. If 0, the capacity is set to the number of objects in set; otherwise capacity must be greater than or equal to the number of objects in array.

    Return Value

    An instance of OSArray containing the objects of set, with a retain count of 1; NULL on failure.

    Discussion

    set must be non-NULL. If capacity is nonzero, it must be greater than or equal to count. The array will grow as needed to accommodate more key-object pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).

    The objects in set are retained for storage in the new set, not copied.