Mac Dev Center Right arrow

Mac OS X Reference Library Right arrow

Drivers, Kernel, & Hardware: Kernel Device Drivers Right arrow

Kernel Framework Reference

OSMetaClassBase

Declared In:

OSMetaClass.h

Overview

OSMetaClassBase is the abstract bootstrap class for the Libkern and I/O Kit run-time type information system.

Discussion

OSMetaClassBase is the abstract C++ root class underlying the entire Libkern and I/O Kit class hierarchy. It defines the run-time type information system, including dynamic class allocation and safe type-casting, as well as the abstract interface for reference counting and a few other utility functions. OSMetaClassBase is the immediate superclass of OSObject and OSMetaClass; no other class should derive from OSMetaClassBase.

For more information, see I/O Kit Device Driver Design Guidelines.

Use by Kernel Extensions

Kernel Extensions should never interact directly with OSMetaClassBase, but they will find useful several macros that tie in to the run-time type information system, specifically:

OSTypeAlloc - allocation of new instances
OSDynamicCast - safe type casting
OSCheckTypeInst - checking for inheritance/derivation
OSMemberFunctionCast - casting C++ member functions to C function pointers for registration as callbacks

See OSMetaClass for more run-time type information interfaces.

Use Restrictions

OSMetaClassBase should not be subclassed by kernel extensions, nor should kernel extensions call its run-time type functions directly.

The run-time type functions and macros are not safe to call in a primary interrupt context.

Concurrency Protection

The run-time type macros and functions of OSMetaClassBase are thread-safe.

Functions

checkTypeInst: Checks whether an object instance is of the same class as another object instance (or a subclass of that class).
getMetaClass: Returns the OSMetaClass representing an OSMetaClassBase subclass.
getRetainCount: Abstract declaration of getRetainCount().
isEqualTo: Checks whether another object is equal to the receiver.
metaCast(const char *): Casts this object is to the class managed by the named OSMetaClass.
metaCast(const OSMetaClass *): Casts this object is to the class managed by the given OSMetaClass.
metaCast(const OSString *): Casts this object is to the class managed by the named OSMetaClass.
metaCast(const OSSymbol *): Casts this object is to the class managed by the named OSMetaClass.
release(): Abstract declaration of release.
release(int): Abstract declaration of release(int freeWhen).
retain: Abstract declaration of retain().
safeMetaCast: Casts an object is to the class managed by the given OSMetaClass.
serialize: Abstract declaration of serialize.
taggedRelease(const void *): Abstract declaration of taggedRelease(const void *).
taggedRelease(const void *, const int): Abstract declaration of taggedRelease(const void *, const int freeWhen).
taggedRetain: Abstract declaration of taggedRetain(const void *).

checkTypeInst

Checks whether an object instance is of the same class as another object instance (or a subclass of that class).

public

static bool checkTypeInst( 
    const OSMetaClassBase * inst, 
    const OSMetaClassBase * typeinst);

Parameters

inst: A pointer to the object to check.
typeinst: A pointer to an object of the class being checked.

Return Value

true if the object is derived from the class of typeinst or a subclass of that class, otherwise false.

Discussion

It is far more convenient to use OSCheckTypeInst.

getMetaClass

Returns the OSMetaClass representing an OSMetaClassBase subclass.

public

virtual const OSMetaClass * getMetaClass() const = 0;

Discussion

OSObject overrides this abstract member function to return the OSMetaClass object that represents each class for run-time typing.

getRetainCount

Abstract declaration of getRetainCount().

public

virtual int getRetainCount() const = 0;

Discussion

See OSObject::getRetainCount().

isEqualTo

Checks whether another object is equal to the receiver.

public

virtual bool isEqualTo(
    const OSMetaClassBase * anObject) const;

Parameters

anObject: The object to copmare to the receiver.

Return Value

true if the objects are equal, false otherwise.

Discussion

OSMetaClassBase implements this as a direct pointer comparison, since it has no other information to judge equality by. Subclasses generally override this function to do a more meaningful comparison. For example, OSString implements it to return true if anObject is derived from OSString and represents the same C string.

metaCast(const char *)

Casts this object is to the class managed by the named OSMetaClass.

public

OSMetaClassBase * metaCast(
    const char * toMeta) const;

Parameters

toMeta: A C string naming the desired target type.

Return Value

this if the object is derived from the class named by toMeta, otherwise NULL.

Discussion

It is far more convenient to use OSDynamicCast.

metaCast(const OSMetaClass *)

Casts this object is to the class managed by the given OSMetaClass.

public

OSMetaClassBase * metaCast(
    const OSMetaClass * toMeta) const;

Parameters

toMeta: A pointer to a constant OSMetaClass for the desired target type.

Return Value

this if the object is derived from the class managed by toMeta, otherwise NULL.

Discussion

It is far more convenient to use OSDynamicCast.

metaCast(const OSString *)

Casts this object is to the class managed by the named OSMetaClass.

public

OSMetaClassBase * metaCast(
    const OSString * toMeta) const;

Parameters

toMeta: An OSString naming the desired target type.

Return Value

this if the object is derived from the class named by toMeta, otherwise NULL.

Discussion

It is far more convenient to use OSDynamicCast.

metaCast(const OSSymbol *)

Casts this object is to the class managed by the named OSMetaClass.

public

OSMetaClassBase * metaCast(
    const OSSymbol * toMeta) const;

Parameters

toMeta: An OSSymbol naming the desired target type.

Return Value

this if the object is derived from the class named by toMeta, otherwise NULL.

Discussion

It is far more convenient to use OSDynamicCast.

release()

Abstract declaration of release.

public

virtual void release() const = 0;

Discussion

See OSObject::release.

release(int)

Abstract declaration of release(int freeWhen).

public

virtual void release(
    int freeWhen) const = 0;

Discussion

See release(int freeWhen).

retain

Abstract declaration of retain().

public

virtual void retain() const = 0;

Discussion

See OSObject::retain().

safeMetaCast

Casts an object is to the class managed by the given OSMetaClass.

public

static OSMetaClassBase * safeMetaCast( 
    const OSMetaClassBase * anObject, 
    const OSMetaClass * toMeta);

Parameters

anObject: A pointer to the object to be cast.
toMeta: A pointer to a constant OSMetaClass for the desired target type.

Return Value

anObject if the object is derived from the class managed by toMeta, otherwise NULL.

Discussion

It is far more convenient to use OSDynamicCast.

serialize

Abstract declaration of serialize.

public

virtual bool serialize(
    OSSerialize *serializer) const = 0;

Discussion

See OSObject::serialize.

taggedRelease(const void *)

Abstract declaration of taggedRelease(const void *).

public

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

Discussion

See OSObject::taggedRelease(const void *).

taggedRelease(const void *, const int)

Abstract declaration of taggedRelease(const void *, const int freeWhen).

protected

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

Discussion

See OSObject::taggedRelease(const void *, const int freeWhen).

taggedRetain

Abstract declaration of taggedRetain(const void *).

public

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

Discussion

See OSObject::taggedRetain(const void *).

Macro Definitions

OSCheckTypeInst: Checks whether two objects are type-compatible.
OSDynamicCast: Safe type-casting for Libkern C++ objects.
OSMemberFunctionCast: Converts a C++ member function pointer, relative to an instance, to a C-style pointer to function.
OSSafeRelease: Release an object if not NULL.
OSSafeReleaseNULL: Release an object if not NULL, then set it to NULL.
OSTypeAlloc: Allocates an instance of the named object class.
OSTypeID: Returns the type ID (metaclass) of a class based on its name.
OSTypeIDInst: Returns the type ID (metaclass) for the class of an object instance.

OSCheckTypeInst

Checks whether two objects are type-compatible.

#define OSCheckTypeInst(typeinst, inst)

Parameters

typeinst: The reference object.
inst: The object to check for type compatibility.

Return Value

true if both inst and typeinst are non-NULL and inst is derived from the class of typeinst; otherwise false.

OSDynamicCast

Safe type-casting for Libkern C++ objects.

#define OSDynamicCast(type, inst)

Parameters

type: The name of the desired class type, as a raw token, not a string or macro. It is assumed you intend to cast to a pointer to an object of this type. Type qualifiers, such as const, are not recognized and will cause a (usually obscure) compile error.
inst: A pointer to the object instance to be cast. May be NULL.

Return Value

inst if it is non-NULL and derived from type; otherwise NULL.

Discussion

OSDynamicCast is a rough equivalent to the standard C++ RTTI dynamic_cast<T> operator. Your code should use this instead of raw C type-casting, and check the resulting value. If the result is non-NULL, the object is safe to use as the type-cast class; if the result is NULL, the object does not derive from the type-cast class and your code should take appropriate steps to handle the error.

OSMemberFunctionCast

Converts a C++ member function pointer, relative to an instance, to a C-style pointer to function.

#define OSMemberFunctionCast(cptrtype, self, func)

Parameters

cptrtype: The function type declaration to cast to (typically provided as a typedef by I/O KitKit classes).
self: The this pointer of the object whose function you wish to cache.
func: The pointer to the member function itself, something like &Class::function.

Return Value

A pointer to a function of the given type referencing self.

Discussion

This function is used to generate pointers to C++ functions for instances, such that they can be registered as callbacks with I/O Kit objects.

No warnings are generated.

This function will panic if an attempt is made to call it with a multiply-inheriting class.

OSSafeRelease

Release an object if not NULL.

#define OSSafeRelease(inst) do { if (inst) (inst)->release(); } while (0)

Parameters

inst: Instance of an OSObject, may be NULL.

OSSafeReleaseNULL

Release an object if not NULL, then set it to NULL.

#define OSSafeReleaseNULL(inst) do { if (inst) (inst)->release(); (inst) = NULL; } while (0)

Parameters

inst: Instance of an OSObject, may be NULL.

OSTypeAlloc

Allocates an instance of the named object class.

#define OSTypeAlloc(type)

Parameters

type: The name of the desired class to be created, as a raw token, not a string or macro.

Return Value

A pointer to the new, uninitialized object on success; NULL on failure.

Discussion

See also OSMetaClass::allocClassWithName(const char *) and OSMetaClass::alloc.

The OSTypeAlloc macro is used to avoid binary compatibility difficulties presented by the C++ new operator.

OSTypeID

Returns the type ID (metaclass) of a class based on its name.

#define OSTypeID(type)

Parameters

type: The name of the desired class, as a raw token, not a string or macro.

Return Value

The unique type ID (metaclass) for the class.

Discussion

It is typically more useful to determine whether a class is derived from another; see OSDynamicCast and OSCheckTypeInst.

OSTypeIDInst

Returns the type ID (metaclass) for the class of an object instance.

#define OSTypeIDInst(typeinst)

Parameters

typeinst: An instance of an OSObject subclass.

Return Value

The type ID of that object's class; that is, its metaclass.

Discussion

It is typically more useful to determine whether an object is derived from a particular class; see OSDynamicCast and OSCheckTypeInst.

Last Updated: 2009-10-14