ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

OSMetaClass

Inherits from:	OSMetaClassBase
Declared In:	OSMetaClass.h

Overview

An instance of OSMetaClass represents one class that the kernel's runtime type information system is aware of.

Functions

alloc: Allocates an instance of the class that this OSMetaClass instance represents.
allocClassWithName: Looks up a metaclass in the runtime type information system and returns the results of an alloc call.
allocClassWithName(const OSString *): Looks up a metaclass in the runtime type information system and returns the results of an alloc call.
allocClassWithName(const OSSymbol *): Looks up a metaclass in the runtime type information system and returns the results of an alloc call.
checkMetaCast: Asks an OSMetaClass instance if the given object is either an instance of it or an instance of a subclass of it.
checkMetaCastWithName: Introspects an object's inheritance tree looking for a class of the given name.
checkMetaCastWithName(const OSString *, const OSMetaClassBase *): Introspects an object's inheritance tree looking for a class of the given name.
checkMetaCastWithName(const OSSymbol *, const OSMetaClassBase *): Introspects an object's inheritance tree looking for a class of the given name.
checkModLoad: Checks if the current load attempt is still OK.
considerUnloads: Schedules module unloading.
getClassName: 'Get'ter for class name.
getClassSize: 'Get'ter for sizeof(class).
getInstanceCount: Gets how many instances of the class have been created.
getKmodName: 'Get'ter for the name of the kmod.
getMetaClassWithName: Looks up a metaclass in the runtime type information system.
getRetainCount: Implements abstract but should no dynamic allocation is allowed.
getSuperClass: 'Get'ter for the super class.
instanceConstructed: Counts the instances of the class behind this metaclass.
instanceDestructed: Removes one instance of the class behind this metaclass.
logError: Logs an error string using printf given an error code.
modHasInstance: Returns whether any of the objects represented by OSMetaClass and associated with the given kernel module name have instances.
OSMetaClass(): Private default constructor.
OSMetaClass(const char *, const OSMetaClass *, unsigned int): Constructor for OSMetaClass objects.
postModLoad: Finishes post processing on a kernel module's metaclasses.
preModLoad: Prepares the runtime type system for the loading of a module.
release(): Implements abstract but should no dynamic allocation is allowed.
release(const void *): Releases a tagged reference to this object.
release(const void *, const int): Releases a tagged reference to this object.
release(int): Implements abstract but should no dynamic allocation is allowed.
reportModInstances: Logs any object that has instances in a module.
retain: Implements abstract but should no dynamic allocation is allowed.
taggedRelease(const void *): Releases a tagged reference to this object.
taggedRelease(const void *, const int): Releases a tagged reference to this object.
taggedRetain: Retains a tagged reference to this object.
~OSMetaClass: Destructor for OSMetaClass objects.

alloc

Allocates an instance of the class that this OSMetaClass instance represents.

public

virtual OSObject *alloc() const = 0;

Return Value

Returns a pointer to a new object with a retain count of 1.

Discussion

This alloc function is analogous to the old ObjC class alloc method. Typically not used by clients because the static function allocClassWithName is more generally useful. In fact, that function is implemented in terms of this virtual function. All subclasses of OSMetaClass must implement this function, but that is what the OSDefineMetaClassAndStructor's families of macros does for the developer automatically.

allocClassWithName

Looks up a metaclass in the runtime type information system and returns the results of an alloc call.

public

static OSObject *allocClassWithName(
    const char *name);

Parameters

name: Name of the desired class.

Return Value

Returns a pointer to a new object, 0 if not found or no memory.

allocClassWithName(const OSString *)

Looks up a metaclass in the runtime type information system and returns the results of an alloc call.

public

static OSObject *allocClassWithName(
    const OSString *name);

Parameters

name: Name of the desired class.

Return Value

Returns a pointer to a new object, 0 if not found or no memory.

allocClassWithName(const OSSymbol *)

Looks up a metaclass in the runtime type information system and returns the results of an alloc call.

public

static OSObject *allocClassWithName(
    const OSSymbol *name);

Parameters

name: Name of the desired class.

Return Value

Returns a pointer to a new object, 0 if not found or no memory.

checkMetaCast

Asks an OSMetaClass instance if the given object is either an instance of it or an instance of a subclass of it.

public

OSMetaClassBase *checkMetaCast(
    const OSMetaClassBase *check) const;

Parameters

check: Pointer of object to introspect.

Return Value

check parameter if cast is valid, 0 otherwise.

checkMetaCastWithName

Introspects an object's inheritance tree looking for a class of the given name.

public

static OSMetaClassBase * checkMetaCastWithName(
    const char *name,
    const OSMetaClassBase *in);

Parameters

name: Name of the desired class or super class.
in: Object to be introspected.

Return Value

in parameter if cast is valid, 0 otherwise.

Discussion

This function is the basis of the kernel dynamic casting mechanism in Mac OS X.

checkMetaCastWithName(const OSString , const OSMetaClassBase )

Introspects an object's inheritance tree looking for a class of the given name.

public

static OSMetaClassBase * checkMetaCastWithName(
    const OSString *name,
    const OSMetaClassBase *in);

Parameters

name: Name of the desired class or super class.
in: Object to be introspected.

Return Value

in parameter if cast is valid, 0 otherwise.

Discussion

This function is the basis of the kernel dynamic casting mechanism in Mac OS X.

checkMetaCastWithName(const OSSymbol , const OSMetaClassBase )

Introspects an object's inheritance tree looking for a class of the given name.

public

static OSMetaClassBase * checkMetaCastWithName(
    const OSSymbol *name,
    const OSMetaClassBase *in);

Parameters

name: Name of the desired class or super class.
in: Object to be introspected.

Return Value

in parameter if cast is valid, 0 otherwise.

Discussion

This function is the basis of the kernel dynamic casting mechanism in Mac OS X.

checkModLoad

Checks if the current load attempt is still OK.

public

static bool checkModLoad(
    void *loadHandle);

Parameters

loadHandle: Handle returned when a successful call to preModLoad is made.

Return Value

Returns true if no errors are outstanding and the system is primed to recieve more objects.

considerUnloads

Schedules module unloading.

public

static void considerUnloads();

Discussion

Schedules unused modules to be unloaded; called when I/O Kit matching goes idle.

getClassName

'Get'ter for class name.

public

const char *getClassName() const;

Return Value

Returns a C string of the class name.

getClassSize

'Get'ter for sizeof(class).

public

unsigned int getClassSize() const;

Return Value

Returns 'sizeof' of the class that this OSMetaClass instance represents.

getInstanceCount

Gets how many instances of the class have been created.

public

unsigned int getInstanceCount() const;

Return Value

Returns the number of instances.

getKmodName

'Get'ter for the name of the kmod.

public

const OSSymbol *getKmodName() const;

Return Value

Returns an OSSymbol representing the kmod name.

getMetaClassWithName

Looks up a metaclass in the runtime type information system.

public

static const OSMetaClass *getMetaClassWithName(const OSSymbol *name);

Parameters

name: Name of the desired class's metaclass.

Return Value

Returns a pointer to a metaclass object if found, 0 otherwise.

getRetainCount

Implements abstract but should no dynamic allocation is allowed.

protected

virtual int getRetainCount() const;

getSuperClass

'Get'ter for the super class.

public

const OSMetaClass *getSuperClass() const;

Return Value

Returns a pointer to superclass, chain ends with 0 for OSObject.

instanceConstructed

Counts the instances of the class behind this metaclass.

public

void instanceConstructed() const;

Discussion

Every non-abstract class that inherits from OSObject has a default constructor that calls its own metaclass's instanceConstructed function. This constructor is defined by the OSDefineMetaClassAndStructors macro (qv) that all OSObject subclasses must use. Also, if the instance count goes from 0 to 1, i.e. the first instance, then increment the instance count of the super class.

instanceDestructed

Removes one instance of the class behind this metaclass.

public

void instanceDestructed() const;

Discussion

OSObject's free function calls this method just before it does a 'delete this' on itself. If the instance count transitions from 1 to 0, i.e. the last object, then one instance of the superclass is also removed.

logError

Logs an error string using printf given an error code.

private

static void logError(
    OSReturn result);

modHasInstance

Returns whether any of the objects represented by OSMetaClass and associated with the given kernel module name have instances.

public

static bool modHasInstance(
    const char *kmodName);

Parameters

kmodName: C string of the kernel module name.

Return Value

Returns true if there are any current instances of any class in the module.

Discussion

Checks all metaclasses associated with the module name and checks their instance counts. This function is used to check to see if a module can be unloaded. Obviously if an instance is still outstanding it isn't safe to unload the code that relies on that object.

OSMetaClass()

Private default constructor.

private

OSMetaClass();

OSMetaClass(const char , const OSMetaClass , unsigned int)

Constructor for OSMetaClass objects.

protected

OSMetaClass(
    const char *inClassName, 
    const OSMetaClass *inSuperClass, 
    unsigned int inClassSize);

Parameters

inClassName: C string of the name of the class this metaclass represents.
inSuperClassName: C string of the name of the super class.
inClassSize: size of the class.

Discussion

This constructor is protected and cannot be used to instantiate an OSMetaClass object, i.e. OSMetaClass is an abstract class. This function stores the currently constructing OSMetaClass instance away for later processing. See preModLoad and postModLoad.

postModLoad

Finishes post processing on a kernel module's metaclasses.

public

static OSReturn postModLoad(
    void *loadHandle);

Parameters

loadHandle: Handle returned when a successful call to preModLoad is made.

Return Value

Returns the error code of the first error encountered.

Discussion

As the order of static object construction is undefined, it is necessary to process the constructors in two phases. These phases rely on global information that is created by the preparation step, preModLoad, which also guarantees single threading between multiple modules. Phase one was the static construction of each metaclass object one by one within the context prepared by the preModLoad call. postModLoad is the second phase of processing. Inserts links all of the super class inheritance chains up, inserts the metaclasses into the global register of classes, and records for each metaclass which kernel module caused its construction. Finally, it cleans up the temporary storage and releases the single threading lock and returns whatever error has been recorded during the construction phase or the post-processing phase.

preModLoad

Prepares the runtime type system for the loading of a module.

public

static void *preModLoad(
    const char *kmodName);

Parameters

kmodName: Globally unique C string name of the kernel module being loaded.

Return Value

Returns a handle to be used in later calls if successful, 0 otherwise.

Discussion

Prepares the runtime type information system for the loading of new all metaclasses constructed between now and the next postModLoad. preModLoad grabs a lock so that the runtime type information system loading can be protected, the lock is released by the postModLoad function. Any OSMetaClass that is constructed between the bracketing pre and post calls will be assosiated with the module name.

release()

Implements abstract but should no dynamic allocation is allowed.

protected

virtual void release() const;

release(const void *)

Releases a tagged reference to this object.

protected

virtual void taggedRelease(
    const void *tag = 0) const;

release(const void *, const int)

Releases a tagged reference to this object.

protected

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

release(int)

Implements abstract but should no dynamic allocation is allowed.

protected

virtual void release(
    int when) const;

Parameters

when: ignored.

reportModInstances

Logs any object that has instances in a module.

public

static void reportModInstances(
    const char *kmodName);

Parameters

kmodName: C string of the kernel module name.

Discussion

When a developer asks for a module to be unloaded but the unload fails due to outstanding instances. This function will report which classes still have instances. It is intended mostly for developers to find problems with unloading classes and will be called automatically by 'verbose' unloads.

retain

Implements abstract but should no dynamic allocation is allowed.

protected

virtual void retain() const;

taggedRelease(const void *)

Releases a tagged reference to this object.

protected

virtual void taggedRelease(
    const void *tag = 0) const;

taggedRelease(const void *, const int)

Releases a tagged reference to this object.

protected

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

taggedRetain

Retains a tagged reference to this object.

protected

virtual void taggedRetain(
    const void *tag = 0) const;

~OSMetaClass

Destructor for OSMetaClass objects.

protected

virtual ~OSMetaClass();

Discussion

If this function is called it means that the object code that implemented this class is actually in the process of unloading. The destructor removes all references to the subclass from the runtime type information system.

Member Data

className

private

const OSSymbol *className;

Discussion

OSSymbol of the class's name.

classSize

private

unsigned int classSize;

Discussion

How big is a single instance of this class.

instanceCount

private

mutable unsigned int instanceCount;

Discussion

Roughly the number of instances of the object. Used primarily as a code-in-use flag.

reserved

private

ExpansionData *reserved;

Discussion

Reserved for future use. (Internal use only)

superClass

See Also:

superClassLink

private

const OSMetaClass *superClassLink;

Discussion

Handle to the superclass's meta class.

superClassLink

See Also:

superClass

private

const OSMetaClass *superClassLink;

Discussion

Handle to the superclass's meta class.

#defines

OSDeclareAbstractStructors

Declares runtime type information data and interfaces (one of the macros used in the class declaration of all subclasses of OSObject).

#define OSDeclareAbstractStructors(className) \ 
    private: \ 
    static const OSMetaClass * const superClass; \ 
    public: \ 
    static const OSMetaClass * const metaClass; \ 
    static class MetaClass : public OSMetaClass { \ 
    public: \ 
    MetaClass(); \ 
    virtual OSObject *alloc() const; \ 
    } gMetaClass; \ 
    friend class className ::MetaClass; \ 
    virtual const OSMetaClass * getMetaClass() const; \ 
    protected: \ 
    className (const OSMetaClass *); \ 
    virtual ~ className (); \ 
    private: \ 
    className (); /* Make primary constructor private in abstract */ \ 
    protected:

Parameters

className: Name of class (NO QUOTES).

Discussion

This macro is used when the class being declared has one or more '= 0' pure virtual methods and thus it is illegal to create an instance of this class. It leaves the current privacy state as 'protected:'.

OSDeclareCommonStructors

DO NOT USE. Basic helper macro for the OSDeclare for Default and Abstract macros, qv.

#define OSDeclareCommonStructors(className) \ 
    private: \ 
    static const OSMetaClass * const superClass; \ 
    public: \ 
    static const OSMetaClass * const metaClass; \ 
    static class MetaClass : public OSMetaClass { \ 
    public: \ 
    MetaClass(); \ 
    virtual OSObject *alloc() const; \ 
    } gMetaClass; \ 
    friend class className ::MetaClass; \ 
    virtual const OSMetaClass * getMetaClass() const; \ 
    protected: \ 
    className (const OSMetaClass *); \ 
    virtual ~ className ()

Parameters

className: Name of class (NO QUOTES).

OSDeclareDefaultStructors

Declares runtime type information data and interfaces (one of the macros used in the class declaration of all subclasses of OSObject).

#define OSDeclareDefaultStructors(className) \ 
    private: \ 
    static const OSMetaClass * const superClass; \ 
    public: \ 
    static const OSMetaClass * const metaClass; \ 
    static class MetaClass : public OSMetaClass { \ 
    public: \ 
    MetaClass(); \ 
    virtual OSObject *alloc() const; \ 
    } gMetaClass; \ 
    friend class className ::MetaClass; \ 
    virtual const OSMetaClass * getMetaClass() const; \ 
    protected: \ 
    className (const OSMetaClass *); \ 
    virtual ~ className (); \ 
    public: \ 
    className (); \ 
    protected:

Parameters

className: Name of class (NO QUOTES).

Discussion

By convention this should be 'called' immediately after the opening brace in a class declaration. It leaves the current privacy state as 'protected:'.

OSDefineAbstractStructors

DO NOT USE. Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv.

#define OSDefineAbstractStructors(className, superClassName) \ 
    OSObject * className ::MetaClass::alloc() const { return 0; }

Parameters

className: Name of class (NO QUOTES and NO MACROS).
superClassName: Name of super class (NO QUOTES and NO MACROS).

OSDefineDefaultStructors

DO NOT USE. Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv.

#define OSDefineDefaultStructors(className, superClassName) \ 
    OSObject * className ::MetaClass::alloc() const \ 
    { return new className; } \ 
    className :: className () : superClassName (&gMetaClass) \ 
    { gMetaClass.instanceConstructed(); }

Parameters

className: Name of class. NO QUOTES and NO MACROS.
superClassName: Name of super class. NO QUOTES and NO MACROS.

OSDefineMetaClass

Defines an OSMetaClass instance, used for backward compatiblility only.

#define OSDefineMetaClass(className, superClassName) \ 
    className ::MetaClass className ::gMetaClass; \ 
    const OSMetaClass * const className ::metaClass = \ 
    & className ::gMetaClass; \ 
    const OSMetaClass * const className ::superClass = \ 
    & superClassName ::gMetaClass; \ 
    \ 
    className :: className(const OSMetaClass *meta) \ 
    : superClassName (meta) { } \ 
    className ::~ className() { } \ 
    const OSMetaClass * className ::getMetaClass() const \ 
    { return &gMetaClass; } \ 
    \ 
    className ::MetaClass::MetaClass() \ 
    : OSMetaClass("className", className::superClass, sizeof(className)) \ 
    { ; }

Parameters

className: Name of class. NO QUOTES and NO MACROS.
superClassName: Name of super class. NO QUOTES and NO MACROS.

OSDefineMetaClassAndAbstractStructors

Defines an OSMetaClass subclass and the runtime system routines.

#define OSDefineMetaClassAndAbstractStructors(className, superClassName) \ 
    className ::MetaClass className ::gMetaClass; \ 
    const OSMetaClass * const className ::metaClass = \ 
    & className ::gMetaClass; \ 
    const OSMetaClass * const className ::superClass = \ 
    & superClassName ::gMetaClass; \ 
    \ 
    className :: className(const OSMetaClass *meta) \ 
    : superClassName (meta) { } \ 
    className ::~ className() { } \ 
    const OSMetaClass * className ::getMetaClass() const \ 
    { return &gMetaClass; } \ 
    \ 
    className ::MetaClass::MetaClass() \ 
    : OSMetaClass("className", className::superClass, sizeof(className)) \ 
    { ; } \ 
    OSObject * className ::MetaClass::alloc() const { return ; }

Parameters

className: Name of class. NO QUOTES and NO MACROS.
superClassName: Name of super class. NO QUOTES and NO MACROS.

Discussion

Define an OSMetaClass subclass and the primary constructors and destructors for a subclass of OSObject that is an abstract class. In general this 'function' is 'called' at the top of the file just before the first function is implemented for a particular class.

OSDefineMetaClassAndAbstractStructorsWithInit

Defines an OSMetaClass subclass and the primary constructors and destructors for a subclass of OSObject that is an abstract class.

#define OSDefineMetaClassAndAbstractStructorsWithInit(className, superClassName, init) \ 
    className ::MetaClass className ::gMetaClass; \ 
    const OSMetaClass * const className ::metaClass = \ 
    & className ::gMetaClass; \ 
    const OSMetaClass * const className ::superClass = \ 
    & superClassName ::gMetaClass; \ 
    \ 
    className :: className(const OSMetaClass *meta) \ 
    : superClassName (meta) { } \ 
    className ::~ className() { } \ 
    const OSMetaClass * className ::getMetaClass() const \ 
    { return &gMetaClass; } \ 
    \ 
    className ::MetaClass::MetaClass() \ 
    : OSMetaClass("className", className::superClass, sizeof(className)) \ 
    { init; } \ 
    OSObject * className ::MetaClass::alloc() const { return ; }

Parameters

className: Name of class (NO QUOTES and NO MACROS).
superClassName: Name of super class (NO QUOTES and NO MACROS).
init: Name of a function to call after the OSMetaClass is constructed.

Discussion

This is the primary definition macro for all abstract classes that are subclasses of OSObject. In general this 'function' is 'called' at the top of the file just before the first function is implemented for a particular class. Once the OSMetaClass has been constructed, at load time, call the init routine. Note: you cannot rely on the order of execution of the init routines.

OSDefineMetaClassAndStructors

Defines an OSMetaClass subclass and the runtime system routines.

#define OSDefineMetaClassAndStructors(className, superClassName) \ 
    className ::MetaClass className ::gMetaClass; \ 
    const OSMetaClass * const className ::metaClass = \ 
    & className ::gMetaClass; \ 
    const OSMetaClass * const className ::superClass = \ 
    & superClassName ::gMetaClass; \ 
    \ 
    className :: className(const OSMetaClass *meta) \ 
    : superClassName (meta) { } \ 
    className ::~ className() { } \ 
    const OSMetaClass * className ::getMetaClass() const \ 
    { return &gMetaClass; } \ 
    \ 
    className ::MetaClass::MetaClass() \ 
    : OSMetaClass("className", className::superClass, sizeof(className)) \ 
    { ; } \ 
    OSObject * className ::MetaClass::alloc() const \ 
    { return new className; } \ 
    className :: className () : superClassName (&gMetaClass) \ 
    { gMetaClass.instanceConstructed(); }

Parameters

className: Name of class. NO QUOTES and NO MACROS.
superClassName: Name of super class. NO QUOTES and NO MACROS.

Discussion

OSDefineMetaClassAndStructorsWithInit

See OSDefineMetaClassAndStructors.

#define OSDefineMetaClassAndStructorsWithInit(className, superClassName, init) \ 
    className ::MetaClass className ::gMetaClass; \ 
    const OSMetaClass * const className ::metaClass = \ 
    & className ::gMetaClass; \ 
    const OSMetaClass * const className ::superClass = \ 
    & superClassName ::gMetaClass; \ 
    \ 
    className :: className(const OSMetaClass *meta) \ 
    : superClassName (meta) { } \ 
    className ::~ className() { } \ 
    const OSMetaClass * className ::getMetaClass() const \ 
    { return &gMetaClass; } \ 
    \ 
    className ::MetaClass::MetaClass() \ 
    : OSMetaClass("className", className::superClass, sizeof(className)) \ 
    { init; } \ 
    OSObject * className ::MetaClass::alloc() const \ 
    { return new className; } \ 
    className :: className () : superClassName (&gMetaClass) \ 
    { gMetaClass.instanceConstructed(); }

Parameters

className: Name of class. NO QUOTES and NO MACROS.
superClassName: Name of super class. NO QUOTES and NO MACROS.
init: Name of a function to call after the OSMetaClass is constructed.

Discussion

Define an OSMetaClass subclass and the primary constructors and destructors for a subclass of OSObject that isn't an abstract class. In general this 'function' is 'called' at the top of the file just before the first function is implemented for a particular class. Once the OSMetaClass has been constructed, at load time, call the init routine. NB you can not rely on the order of execution of the init routines.

OSDefineMetaClassWithInit

DO NOT USE. Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv.

#define OSDefineMetaClassWithInit(className, superClassName, init) \ 
    /* Class global data */ \ 
    className ::MetaClass className ::gMetaClass; \ 
    const OSMetaClass * const className ::metaClass = \ 
    & className ::gMetaClass; \ 
    const OSMetaClass * const className ::superClass = \ 
    & superClassName ::gMetaClass; \ 
    /* Class member functions */ \ 
    className :: className(const OSMetaClass *meta) \ 
    : superClassName (meta) { } \ 
    className ::~ className() { } \ 
    const OSMetaClass * className ::getMetaClass() const \ 
    { return &gMetaClass; } \ 
    /* The ::MetaClass constructor */ \ 
    className ::MetaClass::MetaClass() \ 
    : OSMetaClass(#className, className::superClass, sizeof(className)) \ 
    { init; }

Parameters

className: Name of class (NO QUOTES and NO MACROS).
superClassName: Name of super class (NO QUOTES and NO MACROS).
init: Name of a function to call after the OSMetaClass is constructed.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19