Functions



OSDeclareAbstractStructors

Abstract: One of the macro's used in the class declaration of all subclasses of OSObject, declares runtime type information data and interfaces.
public:

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:'.

Parameters

NameDescription
classNameName of class. NO QUOTES.

OSDeclareCommonStructors

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

Parameters

NameDescription
classNameName of class. NO QUOTES.

OSDeclareDefaultStructors

Abstract: One of the macro's used in the class declaration of all subclasses of OSObject, declares runtime type information data and interfaces.
public:

Macro used in the class declaration all subclasses of OSObject, declares runtime type information data and interfaces. By convention it should be 'called' immediately after the opening brace in a class declaration. It leaves the current privacy state as 'protected:'.

Parameters

NameDescription
classNameName of class. NO QUOTES.

OSDefineAbstractStructors

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

Parameters

NameDescription
classNameName of class. NO QUOTES and NO MACROS.
superClassNameName of super class. NO QUOTES and NO MACROS.

OSDefineDefaultStructors

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

Parameters

NameDescription
classNameName of class. NO QUOTES and NO MACROS.
superClassNameName of super class. NO QUOTES and NO MACROS.

OSDefineMetaClass

Abstract: Define an OSMetaClass instance, used for backward compatiblility only.
public:

Parameters

NameDescription
classNameName of class. NO QUOTES and NO MACROS.
superClassNameName of super class. NO QUOTES and NO MACROS.

OSDefineMetaClassAndAbstractStructors

Abstract: Define an OSMetaClass subclass and the runtime system routines.
public:

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.

Parameters

NameDescription
classNameName of class. NO QUOTES and NO MACROS.
superClassNameName of super class. NO QUOTES and NO MACROS.

OSDefineMetaClassAndAbstractStructorsWithInit

Abstract: Primary definition macro for all abstract classes that a subclasses of OSObject.
public:

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

Parameters

NameDescription
classNameName of class. NO QUOTES and NO MACROS.
superClassNameName of super class. NO QUOTES and NO MACROS.
initName of a function to call after the OSMetaClass is constructed.

OSDefineMetaClassAndStructors

Abstract: Define an OSMetaClass subclass and the runtime system routines.
public:

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.

Parameters

NameDescription
classNameName of class. NO QUOTES and NO MACROS.
superClassNameName of super class. NO QUOTES and NO MACROS.

OSDefineMetaClassAndStructorsWithInit

Abstract: See OSDefineMetaClassAndStructors
public:

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.

Parameters

NameDescription
classNameName of class. NO QUOTES and NO MACROS.
superClassNameName of super class. NO QUOTES and NO MACROS.
initName of a function to call after the OSMetaClass is constructed.

OSDefineMetaClassWithInit

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

Parameters

NameDescription
classNameName of class. NO QUOTES and NO MACROS.
superClassNameName of super class. NO QUOTES and NO MACROS.
initName of a function to call after the OSMetaClass is constructed.

OSMetaClass

Abstract: Private the default constructor
private:

OSMetaClass();


OSMetaClass

Abstract: Constructor for OSMetaClass objects
protected:

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

This constructor is protected and cannot not 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.

Parameters

NameDescription
inClassNamecString of the name of the class this meta-class represents.
inSuperClassNamecString of the name of the super class.
inClassSizesizeof the class.

alloc

Abstract: Allocate an instance of the class that this OSMetaClass instance represents.
public:

virtual OSObject *alloc() const = 0;

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

Result: Pointer to a new object with a retain count of 1.

allocClassWithName

Abstract: Lookup a meta-class in the runtime type information system and return the results of an alloc call.
public:

static OSObject *allocClassWithName(const char *name);

Parameters

NameDescription
nameName of the desired class.
Result: pointer to an new object, 0 if not found or so memory.

allocClassWithName

Abstract: Lookup a meta-class in the runtime type information system and return the results of an alloc call.
public:

static OSObject *allocClassWithName(const OSSymbol *name);

Parameters

NameDescription
nameName of the desired class.
Result: pointer to an new object, 0 if not found or so memory.

allocClassWithName

Abstract: Lookup a meta-class in the runtime type information system and return the results of an alloc call.
public:

static OSObject *allocClassWithName(const OSString *name);

Parameters

NameDescription
nameName of the desired class.
Result: pointer to an new object, 0 if not found or so memory.

checkMetaCast

Abstract: Ask a OSMetaClass instance if the given object is either an instance of it or an instance of a subclass of it.
public:

OSObject *checkMetaCast(const OSObject *check) const;

Parameters

NameDescription
checkPointer of object to introspect.
Result: check parameter if cast valid, 0 otherwise.

checkMetaCastWithName

Abstract: Introspect an objects inheritance tree looking for a class of the given name. Basis of MacOSX's kernel dynamic casting mechanism.
public:

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

Parameters

NameDescription
nameName of the desired class or super class.
inobject to be introspected.
Result: in parameter if cast valid, 0 otherwise.

checkMetaCastWithName

Abstract: Introspect an objects inheritance tree looking for a class of the given name. Basis of MacOSX's kernel dynamic casting mechanism.
public:

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

Parameters

NameDescription
nameName of the desired class or super class.
inobject to be introspected.
Result: in parameter if cast valid, 0 otherwise.

checkMetaCastWithName

Abstract: Introspect an objects inheritance tree looking for a class of the given name. Basis of MacOSX's kernel dynamic casting mechanism.
public:

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

Parameters

NameDescription
nameName of the desired class or super class.
inobject to be introspected.
Result: in parameter if cast valid, 0 otherwise.

checkModLoad

Abstract: Check if the current load attempt is still OK.
public:

static bool checkModLoad(void *loadHandle);

Parameters

NameDescription
loadHandleHandle returned when a successful call to preModLoad is made.
Result: true if no error's are outstanding and the system is primed to recieve more objects.

failModLoad

Abstract: Record an error during the loading of an kernel module.
public:

static void failModLoad(OSReturn error);

As constructor's can't return errors nor can they through exceptions in embedded-c++ an indirect error mechanism is necessary. Check mod load returns a bool to indicate the current error state of the runtime type information system. During object construction a call to failModLoad will cause an error code to be recorded. Once an error has been set the continuing construction will be ignored until the end of the pre/post load.

Parameters

NameDescription
errorCode of the error.

free

Abstract: Don't allow OSObject::free to be called
protected:

virtual void free();

The allocation strategies implemented by OSObject don't work for OSMetaClasses, as OSObjects assume that all object are allocated using new and thus they must all be removed using delete, or in fact free. As OSMetaClass is always a statically defined object, see OSDefineMetaClass, it isn't appropriate for any attempt to be made to implement the default reference counting and free mechanism..


getClassName

Abstract: 'Get'ter for class name.
public:

const char *getClassName() const;

Result: cString of the class name.

getClassSize

Abstract: 'Get'ter for sizeof(class).
public:

unsigned int getClassSize() const;

Result: sizeof of class that this OSMetaClass instance represents.

getInstanceCount

Abstract: How many instances of the class have been created.
public:

unsigned int getInstanceCount() const;

Result: Count of the number of instances.

getMetaClassWithName

Abstract: Lookup a meta-class in the runtime type information system
public:

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

Parameters

NameDescription
nameName of the desired class's meta-class.
Result: pointer to a meta-class object if found, 0 otherwise.

getMetaClassWithName

Abstract: Lookup a meta-class in the runtime type information system
public:

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

Parameters

NameDescription
nameName of the desired class's meta-class.
Result: pointer to a meta-class object if found, 0 otherwise.

getMetaClassWithName

Abstract: Lookup a meta-class in the runtime type information system
public:

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

Parameters

NameDescription
nameName of the desired class's meta-class.
Result: pointer to a meta-class object if found, 0 otherwise.

getSuperClass

Abstract: 'Get'ter for the super class.
public:

const OSMetaClass *getSuperClass() const;

Result: Pointer to superclass, chain ends with 0 for OSObject.

instanceConstructed

Abstract: Counts the instances of the class behind this metaclass.
public:

void instanceConstructed() const;

Every non-abstract class that inherits from OSObject has a default constructor that calls it's own meta-class' 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, ie the first instance, then increment the instance count of the super class


instanceDestructed

Abstract: Removes one instance of the class behind this metaclass.
public:

void instanceDestructed() const;

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 superclasses is also removed.


logError

Abstract: Given an error code log an error string using printf
private:

static void logError(OSReturn result);


modHasInstance

Abstract: Do any of the objects represented by OSMetaClass and associated with the given kernel module name have instances?
public:

static bool modHasInstance(const char *kmodName);

Check all meta-classes associated with the module name and check 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.

Parameters

NameDescription
kmodNamecString of the kernel module name.
Result: true if there are any current instances of any class in the module.

postModLoad

Abstract: Finish postprocessing on a kernel module's meta-classes.
public:

static OSReturn postModLoad(void *loadHandle);

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 be the preparation step, preModLoad, which also guarantees single threading between multiple modules. Phase one was the static construction of each meta-class object one by one withing 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 meta-classes into the global register of classes and records for each meta-class which kernel module caused it's construction. Finally it cleans up the temporary storage and releases the single threading lock and returns whatever error has been recorded in during the construction phase or the post processing phase.

Parameters

NameDescription
loadHandleHandle returned when a successful call to preModLoad is made.
Result: Error code of the first error encountered.

preModLoad

Abstract: Prepare the runtime type system for the load of a module.
public:

static void *preModLoad(const char *kmodName);

Prepare the runtime type information system for the loading of new all meta-classes constructed between now and the next postModLoad. preModLoad grab's 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.

Parameters

NameDescription
kmodNameglobally unique cString name of the kernel module being loaded.
Result: If success full return a handle to be used in later calls 0 otherwise.

release

Abstract: Don't allow OSObject::release to be called, see free
protected:

virtual void release();


reportModInstances

Abstract: Log any object that has instances in a module.
public:

static void reportModInstances(const char *kmodName);

When a developer ask 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.

Parameters

NameDescription
kmodNamecString of the kernel module name.

retain

Abstract: Don't allow OSObject::retain to be called, see free
protected:

virtual void retain();


~OSMetaClass

Abstract: Destructor for OSMetaClass objects
protected:

virtual ~OSMetaClass();

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 reference's to the subclass from the runtime type information system.


© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)