OSObject |
Inherits from: | |
Declared In: |
OSObject is the concrete root class of the Libkern and I/O Kit C++ class hierarchy.
OSObject defines the minimal functionality required of Libkern and I/O Kit C++ classes: tie-in to the run-time type information facility, the dynamic allocation/initialization paradigm, and reference counting. While kernel extensions are free to use their own C++ classes internally, any interaction they have with Libkern or the I/O Kit will require classes ultimately derived from OSObject.
Run-Time Type Information
OSObject is derived from the abstract root class OSMetaClassBase, which declares (and defines many of) the primitives on which the run-time type information facility is based. A parallel inheritance hierarchy of metaclass objects provides run-time introspection, including access to class names, inheritance, and safe type-casting. See OSMetaClass for more information.
Dynamic Allocation/Initialization
The kernel-resident C++ runtime does not support exceptions,
so Libkern classes cannot use standard C++ object
constructors and destructors,
which use exceptions to report errors.
To support error-handling during instance creation, then,
OSObject separates object allocation from initialization.
You can create a new OSObject-derived instance
with the new
operator,
but this does nothing more than allocate memory
and initialize the reference count to 1.
Following this, you must call a designated initialization function
and check its bool
return value.
If the initialization fails,
you must immediately call
release
on the instance and handle the failure in whatever way is appropriate.
Many Libkern and I/O Kit classes define static instance-creation functions
(beginning with the word "with")
to make construction a one-step process for clients.
Reference Counting
OSObject provides reference counting services using the
retain
,
release()
,
release(int freeWhen)
and
free
functions.
The public interface to the reference counting is
retain
,
and
release
;
release(int freeWhen)
is provided
for objects that have internal retain cycles.
In general, a subclass is expected to only override
free
.
It may also choose to override
release(int freeWhen)
if the object has a circular retain count, as noted above.
Use Restrictions
With very few exceptions in the I/O Kit, all Libkern-based C++ classes, functions, and macros are unsafe to use in a primary interrupt context. Consult the I/O Kit documentation related to primary interrupts for more information.
Concurrency Protection
The basic features of OSObject are thread-safe. Most Libkern subclasses are not, and require locking or other protection if instances are shared between threads. I/O Kit driver objects are either designed for use within thread-safe contexts or designed to inherently be thread-safe. Always check the individual class documentation to see what steps are necessary for concurrent use of instances.
Deallocates/releases resources held by the object.
Returns the reference count of the object.
Initializes a newly-allocated object.
Frees the memory of the object itself.
Allocates memory for an instance of the class.
Releases a reference to the object, freeing it immediately if the reference count drops to zero.
Releases a reference to an object, freeing it immediately if the reference count drops below the specified threshold.
Retains a reference to the object.
Overridden by subclasses to archive the receiver into the provided OSSerialize object.
Releases a tagged reference to an object, freeing it immediately if the reference count drops to zero.
Releases a tagged reference to an object, freeing it immediately if the reference count drops below the specified threshold.
Retains a reference to the object with an optional tag used for reference-tracking.
free |
Deallocates/releases resources held by the object.
Classes derived from OSObject should override this function to deallocate or release all dynamic resources held by the instance, then call the superclass's implementation.
Caution:
You can not assume that you have completed initialization
before free
is called,
so be very careful in your implementation.
OSObject's implementation performs the C++ delete
of the instance, so be sure that you call the superclass
implementation last in your implementation.
free
must not fail;
all resources must be deallocated or released on completion.
getRetainCount |
Returns the reference count of the object.
public
virtual int getRetainCount() const;
The reference count of the object.
init |
Initializes a newly-allocated object.
protected
virtual bool init();
true
on success, false
on failure.
Classes derived from OSObject must override the primary init method
of their parent.
In general most implementations call
super::init()
before doing local initialisation.
If the superclass call fails then return false
immediately.
If the subclass encounters a failure then it should return false
.
operator delete |
Frees the memory of the object itself.
mem
A pointer to the object's memory.
size
The size of the object's block of memory.
Never use delete
on objects derived from OSObject;
use
release
instead.
operator new |
Allocates memory for an instance of the class.
public
static void * operator new( size_t size);
size
The number of bytes to allocate
A pointer to block of memory if available, NULL
otherwise.
release() |
Releases a reference to the object, freeing it immediately if the reference count drops to zero.
public
virtual void release() const;
This function decrements the reference count of the receiver by 1.
If the reference count drops to zero,
the object is immediately freed using
free
.
release(int) |
Releases a reference to an object, freeing it immediately if the reference count drops below the specified threshold.
protected
virtual void release( int freeWhen) const;
freeWhen
If decrementing the reference count makes it
>= freeWhen
, the object is immediately freed.
If the receiver has freeWhen
or fewer references
after its reference count is decremented,
it is immediately freed.
This version of release
can be used to break certain retain cycles in object graphs.
In general, however, it should be avoided.
retain |
Retains a reference to the object.
public
virtual void retain() const;
This function increments the reference count of the receiver by 1. If you need to maintain a reference to an object outside the context in which you received it, you should always retain it immediately.
serialize |
Overridden by subclasses to archive the receiver into the provided OSSerialize object.
public
virtual bool serialize( OSSerialize *serializer) const;
serializer
The OSSerialize object.
true
if serialization succeeds, false
if not.
OSObject's implementation writes a string indicating that the class of the object receiving the function call is not serializable. Subclasses that can meaningfully encode themselves in I/O Kit-style property list XML can override this function to do so. See OSSerialize for more information.
taggedRelease(const void *) |
Releases a tagged reference to an object, freeing it immediately if the reference count drops to zero.
tag
Used for tracking collection references.
Kernel extensions should not use this function. It is for use by OSCollection and subclasses to track inclusion in collections.
taggedRelease(const void *, const int) |
Releases a tagged reference to an object, freeing it immediately if the reference count drops below the specified threshold.
tag
Used for tracking collection references.
freeWhen
If decrementing the reference count makes it
>= freeWhen
, the object is immediately freed.
Kernel extensions should not use this function. It is for use by OSCollection and subclasses to track inclusion in collections.
If the receiver has freeWhen
or fewer references
after its reference count is decremented,
it is immediately freed.
This version of release
can be used to break certain retain cycles in object graphs.
In general, however, it should be avoided.
taggedRetain |
Retains a reference to the object with an optional tag used for reference-tracking.
tag
Used for tracking collection references.
Kernel extensions should not use this function. It is for use by OSCollection and subclasses to track inclusion in collections.
If you need to maintain a reference to an object outside the context in which you received it, you should always retain it immediately.
Last Updated: 2010-07-29