OSMetaClassBase

Availability
Available in OS X v10.0 and later.
Declared in
OSMetaClass.h

Overview

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

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:

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.

Tasks

Miscellaneous

Instance Methods

checkTypeInst

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

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.

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().

virtual int getRetainCount() const = 0;
Discussion

See OSObject::getRetainCount().

isEqualTo

Checks whether another object is equal to the receiver.

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.

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.

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.

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.

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.

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSMetaClass.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSMetaClass.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
OSMetaClass.h

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSMetaClass.h

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
OSMetaClass.h

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.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
OSMetaClass.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSMetaClass.h

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
OSMetaClass.h

release()

Abstract declaration of release.

virtual void release() const = 0;
Discussion

See OSObject::release.

release(int)

Abstract declaration of release(int freeWhen).

virtual void release( int freeWhen) const = 0;
Discussion

See release(int freeWhen).

retain

Abstract declaration of retain().

virtual void retain() const = 0;
Discussion

See OSObject::retain().

safeMetaCast

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

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.

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

See OSObject::serialize.

taggedRelease(const void *)

Abstract declaration of taggedRelease(const void *).

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).

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 *).

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

See OSObject::taggedRetain(const void *).