Overview

OSSymbol wraps a C string in a unique C++ object for use as keys in Libkern collections.

Discussion

OSSymbol is a container class for managing uniqued strings, for example, those used as dictionary keys. Its static instance-creation functions check for an existing instance of OSSymbol with the requested C string value before creating a new object. If an instance already exists in the pool of unique symbols, its reference count is incremented and the existing instance is returned.

While OSSymbol provides for uniquing of a given string value, it makes no effort to enforce immutability of that value. Altering the contents of an OSSymbol should be avoided.

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.

OSSymbol 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

free

Overrides OSObject::free to synchronize with the symbol pool.

initWithCString

Overridden to prevent creation of duplicate symbols.

initWithCStringNoCopy

Overridden to prevent creation of duplicate symbols.

initWithString

Overridden to prevent creation of duplicate symbols.

isEqualTo

Tests the equality of an OSSymbol object to an arbitrary object.

isEqualTo(const char *)

Tests the equality of an OSSymbol object with a C string.

isEqualTo(const OSSymbol *)

Tests the equality of two OSSymbol objects.

taggedRelease(const void *)

Overrides OSObject::taggedRelease(const void *) to synchronize with the symbol pool.

taggedRelease(const void *, const int)

Overrides OSObject::taggedRelease(const void *, const int) to synchronize with the symbol pool.

withCString

Returns an OSSymbol created from a C string, or the existing unique instance of the same value.

withCStringNoCopy

Returns an OSSymbol created from a C string, without copying that string, or the existing unique instance of the same value.

withString

Returns an OSSymbol created from an OSString, or the existing unique instance of the same value.

Overrides OSObject::free to synchronize with the symbol pool.

protected

virtual void free(); 

Discussion

Because OSSymbol shares instances, the reference-counting functions must synchronize access to the class-internal tables used to track those instances.

Overridden to prevent creation of duplicate symbols.

private

virtual bool initWithCString(
    const char *cString); 

Parameters

Return Value

false.

Discussion

Overrides OSString's implementation to prevent creation of distinct OSSymbols with the same string value.

Overridden to prevent creation of duplicate symbols.

private

virtual bool initWithCStringNoCopy(
    const char *cString); 

Parameters

Return Value

false.

Discussion

Overrides OSString's implementation to prevent creation of distinct OSSymbols with the same string value.

Overridden to prevent creation of duplicate symbols.

private

virtual bool initWithString(
    const OSString *aString); 

Parameters

Return Value

false.

Discussion

Overrides OSString's implementation to prevent creation of distinct OSSymbols with the same string value.

Tests the equality of an OSSymbol object to an arbitrary object.

public

virtual bool isEqualTo(
    const OSMetaClassBase *anObject) const; 

Parameters

Return Value

Returns true if the two objects are equivalent, false otherwise.

Discussion

An OSSymbol is considered equal to another object if that object is derived from OSString and contains the equivalent bytes of the same length.

Tests the equality of an OSSymbol object with a C string.

public

virtual bool isEqualTo(
    const char *cString) const; 

Parameters

Return Value

true if the OSSymbol's characters are equivalent to the C string's, false otherwise.

Tests the equality of two OSSymbol objects.

public

virtual bool isEqualTo(
    const OSSymbol *aSymbol) const; 

Parameters

Return Value

true if the two OSSymbol objects are equivalent, false otherwise.

Discussion

Two OSSymbol objects are considered equal if they have the same address; that is, this function is equivalent to the == operator.

Overrides OSObject::taggedRelease(const void *) to synchronize with the symbol pool.

public

virtual void taggedRelease(
    const void *tag) const; 

Parameters

Discussion

Because OSSymbol shares instances, the reference-counting functions must synchronize access to the class-internal tables used to track those instances.

Overrides OSObject::taggedRelease(const void *, const int) to synchronize with the symbol pool.

protected

virtual void taggedRelease( 
    const void *tag, 
    const int freeWhen) const; 

Parameters

Discussion

Because OSSymbol shares instances, the reference-counting functions must synchronize access to the class-internal tables used to track those instances.

Returns an OSSymbol created from a C string, or the existing unique instance of the same value.

public

static const OSSymbol * withCString(
    const char *cString); 

Parameters

Return Value

An instance of OSSymbol representing the same characters as cString; NULL on failure.

Discussion

This function returns the unique OSSymbol instance representing the string value of cString. You can compare it with other OSSymbols using the == operator.

OSSymbols are reference-counted normally. This function either returns a new OSSymbol with a retain count of 1, or increments the retain count of the existing instance.

Returns an OSSymbol created from a C string, without copying that string, or the existing unique instance of the same value.

public

static const OSSymbol * withCStringNoCopy(
    const char *cString); 

Parameters

Return Value

An instance of OSSymbol representing the same characters as cString; NULL.

Discussion

Avoid using this function; OSSymbols should own their internal string buffers.

This function returns the unique OSSymbol instance representing the string value of cString. You can compare it with other OSSymbols using the == operator.

OSSymbols are reference-counted normally. This function either returns a new OSSymbol with a retain count of 1, or increments the retain count of the existing instance.

Returns an OSSymbol created from an OSString, or the existing unique instance of the same value.

public

static const OSSymbol * withString(
    const OSString *aString); 

Parameters

Return Value

An instance of OSSymbol representing the same characters as aString; NULL on failure.

Discussion

This function creates or returns the unique OSSymbol instance representing the string value of aString. You can compare it with other OSSymbols using the == operator.

OSSymbols are reference-counted normally. This function either returns a new OSSymbol with a retain count of 1, or increments the retain count of the existing instance.

Last Updated: 2010-07-29