#include <libkern/c++/OSSymbol.h>
libkern/c++/OSSymbol.h
IOSymbol.h created by gvdl on Fri 1998-10-30
typedefOSSymbolPtr
typedef OSSymbol* OSSymbolPtr
typedefOSSymbolConstPtr
typedef OSSymbol const* OSSymbolConstPtr
classOSSymbol
@class OSSymbol
@abstract 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.
<b>Use Restrictions</b>
With very few exceptions in the I/O Kit, all Libkern-based C++
classes, functions, and macros are <b>unsafe</b>
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
@link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link,
handle synchronization via defined member functions for setting
properties.
: public OSString
APPLE_KEXT_OVERRIDE
virtual void taggedRetain(const void * tag) constvirtual protected@function taggedRetain
@abstract Overrides
<code>@link
//apple_ref/cpp/instm/OSObject/taggedRetain/virtualvoid/(constvoid*)
OSObject::taggedRetain(const void *) const@/link</code>
to synchronize with the symbol pool.
@param tag Used for tracking collection references.
APPLE_KEXT_OVERRIDE
virtual void taggedRelease(const void * tag, const int freeWhen) constvirtual protected@function taggedRelease
@abstract Overrides
<code>@link
//apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint)
OSObject::taggedRelease(const void *, const int)@/link</code>
to synchronize with the symbol pool.
@param tag Used for tracking collection references.
@param freeWhen If decrementing the reference count makes it
>= <code>freeWhen</code>, the object is immediately freed.
@discussion Because OSSymbol shares instances, the reference-counting functions
must synchronize access to the class-internal tables
used to track those instances.
APPLE_KEXT_OVERRIDE
virtual void free()virtual protectedxx-review: should we just omit this from headerdoc?
@function free
@abstract Overrides
<code>@link
//apple_ref/cpp/instm/OSObject/free/virtualvoid/()
OSObject::free@/link</code>
to synchronize with the symbol pool.
@discussion Because OSSymbol shares instances, the reference-counting functions
must synchronize access to the class-internal tables
used to track those instances.
APPLE_KEXT_OVERRIDE
virtual void taggedRelease(const void * tag) constvirtualOriginal note (not for headerdoc):
The C++ language has forced me to override this method
even though I have implemented it as
<code>{ super::taggedRelease(tag) }</code>.
It seems that C++ is confused about the appearance of the protected
taggedRelease with 2 parameters and refuses to only inherit one function.
See
<code>@link
//apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint)
OSObject::taggedRelease(const void *, const int)@/link</code>.
static OSPtr<const OSSymbol> withString(const OSString * aString)static
@function withString
@abstract Returns an OSSymbol created from an OSString,
or the existing unique instance of the same value.
@param aString The OSString object to look up or copy.
@result An instance of OSSymbol
representing the same characters as <code>aString</code>;
<code>NULL</code> on failure.
@discussion This function creates or returns the unique OSSymbol instance
representing the string value of <code>aString</code>.
You can compare it with other OSSymbols using the <code>==</code> 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.
static OSPtr<const OSSymbol> withCString(const char * cString)static
@function withCString
@abstract Returns an OSSymbol created from a C string,
or the existing unique instance of the same value.
@param cString The C string to look up or copy.
@result An instance of OSSymbol representing
the same characters as <code>cString</code>;
<code>NULL</code> on failure.
@discussion This function returns the unique OSSymbol instance
representing the string value of <code>cString</code>.
You can compare it with other OSSymbols using the <code>==</code> 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.
static OSPtr<const OSSymbol> withCStringNoCopy(const char * cString)static
@function withCStringNoCopy
@abstract Returns an OSSymbol created from a C string,
without copying that string,
or the existing unique instance of the same value.
@param cString The C string to look up or use.
@result An instance of OSSymbol representing
the same characters as <code>cString</code>;
<code>NULL</code>.
@discussion Avoid using this function;
OSSymbols should own their internal string buffers.
This function returns the unique OSSymbol instance
representing the string value of <code>cString</code>.
You can compare it with other OSSymbols using the <code>==</code> 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.
static OSPtr<const OSSymbol> existingSymbolForString(const OSString *aString)static
@function existingSymbolForString
@abstract Returns an existing OSSymbol for the given OSString.
@param aString The OSString Object to look up.
@result An existing instance of OSSymbol representing
the same characters as <code>aString</code>;
<code>NULL</code> if none is found.
@discussion The returned OSSymbol object is returned with an incremented refcount
that needs to be released.
static OSPtr<const OSSymbol> existingSymbolForCString(const char *aCString)static
@function existingSymbolForCString
@abstract Returns an existing OSSymbol for the given C string.
@param aCString The C string to look up.
@result An existing instance of OSSymbol representing
the same characters as <code>aString</code>;
<code>NULL</code> if none is found.
@discussion The returned OSSymbol object is returned with an incremented refcount
that needs to be released.
virtual bool isEqualTo(const OSSymbol * aSymbol) constvirtual
@function isEqualTo
@abstract Tests the equality of two OSSymbol objects.
@param aSymbol The OSSymbol object being compared against the receiver.
@result <code>true</code> if the two OSSymbol objects are equivalent,
<code>false</code> otherwise.
@discussion Two OSSymbol objects are considered equal if they have the same address;
that is, this function is equivalent to the <code>==</code> operator.
APPLE_KEXT_OVERRIDE
virtual bool isEqualTo(const char * cString) constvirtual@function isEqualTo
@abstract Tests the equality of an OSSymbol object with a C string.
@param cString The C string to compare against the receiver.
@result <code>true</code> if the OSSymbol's characters
are equivalent to the C string's,
<code>false</code> otherwise.
APPLE_KEXT_OVERRIDE virtual bool isEqualTo(const OSMetaClassBase * anObject) constvirtual
@function isEqualTo
@abstract Tests the equality of an OSSymbol object to an arbitrary object.
@param anObject The object to be compared against the receiver.
@result Returns <code>true</code> if the two objects are equivalent,
<code>false</code> otherwise.
@discussion An OSSymbol is considered equal to another object
if that object is derived from
@link //apple_ref/doc/class/OSMetaClassBase OSString@/link
and contains the equivalent bytes of the same length.