OSSet

Inherits from:
Declared In:

Overview

OSSet provides an unordered set store of objects.

Discussion

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.


Functions

containsObject

Checks the set for the presence of an object.

copyCollection

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

ensureCapacity

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

flushCollection

Removes and releases all objects within the set.

free

Deallocates or releases any resources used by the OSSet instance.

getAnyObject

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

getCapacity

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

getCapacityIncrement

Returns the storage increment of the set.

getCount

Returns the current number of objects within the set.

initWithArray

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

initWithCapacity

Initializes a new instance of OSSet.

initWithObjects

Initializes a new OSSet populated with objects provided.

initWithSet

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

isEqualTo(const OSMetaClassBase *)

Tests the equality of an OSSet against an arbitrary object.

isEqualTo(const OSSet *)

Tests the equality of two OSSet objects.

member

Checks the set for the presence of an object.

merge(const OSArray *)

Adds the contents of an OSArray to the set.

merge(const OSSet *)

Adds the contents of an OSet to the set.

removeObject

Removes an object from the set.

serialize

Archives the receiver into the provided OSSerialize object.

setCapacityIncrement

Sets the storage increment of the set.

setObject

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

setOptions

Recursively sets option bits in the set and all child collections.

withArray

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

withCapacity

Creates and initializes an empty OSSet.

withObjects

Creates and initializes an OSSet populated with objects provided.

withSet

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

containsObject

Checks the set for the presence of an object. 

public

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.

copyCollection

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

public

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.

ensureCapacity

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

public

virtual unsigned int ensureCapacity(
    unsigned int newCapacity);
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.

flushCollection

Removes and releases all objects within the set. 

public

virtual void flushCollection();
Discussion

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

free

Deallocates or releases any resources used by the OSSet instance. 

public

virtual void free();
Discussion

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

getAnyObject

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

public

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.

getCapacity

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

public

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.

getCapacityIncrement

Returns the storage increment of the set. 

public

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.

getCount

Returns the current number of objects within the set. 

public

virtual unsigned int getCount() const;
Return Value

The current number of objects within the set.

initWithArray

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

public

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.

initWithCapacity

Initializes a new instance of OSSet. 

public

virtual bool initWithCapacity(
    unsigned int capacity);
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).

initWithObjects

Initializes a new OSSet populated with objects provided. 

public

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.

initWithSet

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

public

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.

isEqualTo(const OSMetaClassBase *)

Tests the equality of an OSSet against an arbitrary object. 

public

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.

isEqualTo(const OSSet *)

Tests the equality of two OSSet objects. 

public

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.

member

Checks the set for the presence of an object. 

public

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.

merge(const OSArray *)

Adds the contents of an OSArray to the set. 

public

virtual bool merge(
    const OSArray * array);
Parameters
array

The OSArray object containing the objects to be added.

Return Value

true if any object from array was successfully added the receiver, false otherwise.

Discussion

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

A false return value can mean either that all the objects in array are already present in the set, or that a memory allocation failure occurred. If you need to know whether the objects are already present, use containsObject for each object.

merge(const OSSet *)

Adds the contents of an OSet to the set. 

public

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 was successfully added the receiver, false otherwise.

Discussion

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

A false return value can mean either that all the objects in array are already present in the set, or that a memory allocation failure occurred. If you need to know whether the objects are already present, use containsObject for each object.

removeObject

Removes an object from the set. 

public

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.

serialize

Archives the receiver into the provided OSSerialize object. 

public

virtual bool serialize(
    OSSerialize *serializer) const;
Parameters
serializer

The OSSerialize object.

Return Value

true if serialization succeeds, false if not.

setCapacityIncrement

Sets the storage increment of the set. 

public

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.

setObject

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

public

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.

setOptions

Recursively sets option bits in the set and all child collections. 

public

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.

withArray

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

public

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.

withCapacity

Creates and initializes an empty OSSet. 

public

static OSSet * withCapacity(
    unsigned int capacity);
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).

withObjects

Creates and initializes an OSSet populated with objects provided. 

public

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.

withSet

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

public

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.

 

 

Last Updated: 2009-10-14