OSMetaClass
Member Functions
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
Name | Description |
className | Name of class. NO QUOTES. |
Abstract: Basic helper macro for the OSDeclare for Default and Abstract macros, qv. DO NOT USE.
public:
Parameters
Name | Description |
className | Name of class. NO QUOTES. |
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
Name | Description |
className | Name of class. NO QUOTES. |
Abstract: Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv. DO NOT USE.
public:
Parameters
Name | Description |
className | Name of class. NO QUOTES and NO MACROS. |
superClassName | Name of super class. NO QUOTES and NO MACROS. |
Abstract: Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv. DO NOT USE.
public:
Parameters
Name | Description |
className | Name of class. NO QUOTES and NO MACROS. |
superClassName | Name of super class. NO QUOTES and NO MACROS. |
Abstract: Define an OSMetaClass instance, used for backward compatiblility only.
public:
Parameters
Name | Description |
className | Name of class. NO QUOTES and NO MACROS. |
superClassName | Name of super class. NO QUOTES and NO MACROS. |
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
Name | Description |
className | Name of class. NO QUOTES and NO MACROS. |
superClassName | Name of super class. NO QUOTES and NO MACROS. |
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
Name | Description |
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. |
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
Name | Description |
className | Name of class. NO QUOTES and NO MACROS. |
superClassName | Name of super class. NO QUOTES and NO MACROS. |
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
Name | Description |
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. |
Abstract: Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv. DO NOT USE.
public:
Parameters
Name | Description |
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. |
Abstract: Private the default constructor
private:
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
Name | Description |
inClassName | cString of the name of the class this meta-class represents. |
inSuperClassName | cString of the name of the super class. |
inClassSize | sizeof the class. |
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.
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
Name | Description |
name | Name of the desired class. |
Result: pointer to an new object, 0 if not found or so memory.
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
Name | Description |
name | Name of the desired class. |
Result: pointer to an new object, 0 if not found or so memory.
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
Name | Description |
name | Name of the desired class. |
Result: pointer to an new object, 0 if not found or so memory.
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
Name | Description |
check | Pointer of object to introspect. |
Result: check parameter if cast valid, 0 otherwise.
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
Name | Description |
name | Name of the desired class or super class. |
in | object to be introspected. |
Result: in parameter if cast valid, 0 otherwise.
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
Name | Description |
name | Name of the desired class or super class. |
in | object to be introspected. |
Result: in parameter if cast valid, 0 otherwise.
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
Name | Description |
name | Name of the desired class or super class. |
in | object to be introspected. |
Result: in parameter if cast valid, 0 otherwise.
Abstract: Check if the current load attempt is still OK.
public:
static bool checkModLoad(void *loadHandle);
Parameters
Name | Description |
loadHandle | Handle 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.
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
Name | Description |
error | Code of the error. |
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..
Abstract: 'Get'ter for class name.
public:
const char *getClassName() const;
Result: cString of the class name.
Abstract: 'Get'ter for sizeof(class).
public:
unsigned int getClassSize() const;
Result: sizeof of class that this OSMetaClass instance represents.
Abstract: How many instances of the class have been created.
public:
unsigned int getInstanceCount() const;
Result: Count of the number of instances.
Abstract: Lookup a meta-class in the runtime type information system
public:
static const OSMetaClass *getMetaClassWithName(const OSSymbol *name);
Parameters
Name | Description |
name | Name of the desired class's meta-class. |
Result: pointer to a meta-class object if found, 0 otherwise.
Abstract: Lookup a meta-class in the runtime type information system
public:
static const OSMetaClass *getMetaClassWithName(const char *name);
Parameters
Name | Description |
name | Name of the desired class's meta-class. |
Result: pointer to a meta-class object if found, 0 otherwise.
Abstract: Lookup a meta-class in the runtime type information system
public:
static const OSMetaClass *getMetaClassWithName(const OSString *name);
Parameters
Name | Description |
name | Name of the desired class's meta-class. |
Result: pointer to a meta-class object if found, 0 otherwise.
Abstract: 'Get'ter for the super class.
public:
const OSMetaClass *getSuperClass() const;
Result: Pointer to superclass, chain ends with 0 for OSObject.
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
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.
Abstract: Given an error code log an error string using printf
private:
static void logError(OSReturn result);
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
Name | Description |
kmodName | cString of the kernel module name. |
Result: true if there are any current instances of any class in the module.
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
Name | Description |
loadHandle | Handle returned when a successful call to preModLoad is made. |
Result: Error code of the first error encountered.
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
Name | Description |
kmodName | globally unique cString name of the kernel module being loaded. |
Result: If success full return a handle to be used in later calls 0 otherwise.
Abstract: Don't allow OSObject::release to be called, see free
protected:
virtual void release();
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
Name | Description |
kmodName | cString of the kernel module name. |
Abstract: Don't allow OSObject::retain to be called, see free
protected:
virtual void retain();
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.
Member Data
private:
const OSSymbol *className;
OSSymbol of the class' name.
private:
unsigned int classSize;
How big is a single instancde of this class.
private:
mutable unsigned int instanceCount;
Roughly number of instances of the object. Used primarily as a code in use flag.
private:
OSMetaClass *superClass;
Handle to the superclass' meta class.
© 2000 Apple Computer, Inc. (Last Updated 2/23/2000)