ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

OSObject

Inherits from:	OSMetaClassBase
Declared In:	OSObject.h

Overview

The root base class for Mac OS X kernel and just generally all-round useful class to have around.

Discussion

Defines the minimum functionality that an object can expect. Implements reference counting, type-safe object casting, allocation primitives and serialization, among other functionality. This object is an abstract base class and cannot be copied, nor can it be constructed by itself.

Construction

The I/O Kit is based upon a restricted subset of C++ that does not allow exceptions. This means that the standard C++ constructors cannot report a failure. Obviously, initialization of a new object can fail so we have had to work around this language limitation. In the Mac OS X kernel we have chosen to break object construction into two phases. Phase one is the familiar C++ new operator, the only initialization is the object has exactly one reference after creation. Once new is called, the client MUST call init and check its return value. If the init call fails then the object MUST be immediately released. The I/O Kit usually implements factory methods to make construction a one-step process for clients.

Reference Counting

OSObject provides reference counting services using the retain(), release(), release(int when) and free() functions. The public interface to the reference counting is retain() & release(). release() is implemented as a simple call to release(1). The actual implementation of release(when) is a little subtle. If the current reference count is less than or equal to the 'when' parameter the object will call free on itself.
In general a subclass is expected to only override free(). It may also choose to override release() if the object has a circular retain count (see release(int when)).

Runtime Type Information System

The Mac OS X C++ implements a basic runtime type information system using metaclass information and a number of macros, OSDynamicCast, OSTypeID, OSTypeIDInst, OSCheckTypeInst and OSMetaClass.

Functions

delete: Releases the 'operator new'ed memory.
free: The last reference is gone so clean up your resources.
getRetainCount: Gets the number of times this object has been retained.
init: Mac OS X kernel's primary mechanism for constructing objects.
new: Allocator for all objects that inherit from OSObject.
operator delete: Releases the 'operator new'ed memory.
operator new: Allocator for all objects that inherit from OSObject.
release(): Releases a reference to this object.
release(int): Implements the untagged release(when) mechanism.
retain: Retains a reference to this object.
serialize: Archives the receiver.
taggedRelease(const void *): Releases a tagged reference to this object.
taggedRelease(const void *, const int): Primary implementation of the tagged release mechanism.
taggedRetain: Retains a tagged reference to this object.

delete

Releases the 'operator new'ed memory.

protected

static void operator delete(
    void *mem,
    size_t size);

Parameters

mem: Pointer to block of memory.
size: Size of block of memory.

Discussion

Never attempt to delete an object that inherits from OSObject directly; use release().

free

The last reference is gone so clean up your resources.

protected

virtual void free();

Discussion

Release all resources held by the object, then call your parent's free().

Caution:

You cannot assume that you have completed initialization before your free is called, so be very careful in your implementation.
The implementation is OSObject::free() { delete this; } so do not call super::free() until just before you return.
Free is not allowed to fail; all resources must be released on completion.

getRetainCount

Gets the number of times this object has been retained.

public

virtual int getRetainCount() const;

Return Value

Returns the current retain count.

init

Mac OS X kernel's primary mechanism for constructing objects.

protected

virtual bool init();

Return Value

OSObject::init always returns true, but subclasses will return false on init failure.

Discussion

Your responsibility as a subclass author is to override the init method of your parent. In general, most of our implementations call super::init() before doing local initialization, if the parent fails then return false immediately. If you have a failure during your local initialization, then return false.

new

Allocator for all objects that inherit from OSObject.

public

static void *operator new(
    size_t size);

Parameters

size: Number of bytes to allocate.

Return Value

Returns pointer to block of memory if available, 0 otherwise.

operator delete

Releases the 'operator new'ed memory.

protected

static void operator delete(
    void *mem,
    size_t size);

Parameters

mem: Pointer to block of memory.
size: Size of block of memory.

Discussion

Never attempt to delete an object that inherits from OSObject directly; use release().

operator new

Allocator for all objects that inherit from OSObject.

public

static void *operator new(
    size_t size);

Parameters

size: Number of bytes to allocate.

Return Value

Returns pointer to block of memory if available, 0 otherwise.

release()

Releases a reference to this object.

public

virtual void release() const;

Discussion

Removes a reference that is NULL tagged. See taggedRelease.

release(int)

Implements the untagged release(when) mechanism.

protected

virtual void release(
    int when) const;

Parameters

when: Pass through to taggedRelease.

retain

Retains a reference to this object.

public

virtual void retain() const;

Discussion

Takes a reference that is NULL tagged. See taggedRetain.

serialize

Archives the receiver.

public

virtual bool serialize(
    OSSerialize *s) const;

Parameters

s: The OSSerialize object.

Return Value

Returns true if serialization was successful, false if not.

taggedRelease(const void *)

Releases a tagged reference to this object.

public

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

Parameters

tag: The tag of the reference.

Discussion

This function removes a reference on this object with the specified tag. If an attempt is made to remove a reference that isn't associated with this tag the kernel will panic immediately.

taggedRelease(const void *, const int)

Primary implementation of the tagged release mechanism.

protected

virtual void taggedRelease(
    const void *tag,
    const int when) const;

Parameters

when: If retainCount == when then call free().

Discussion

If retainCount

taggedRetain

Retains a tagged reference to this object.

public

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

Parameters

tag: The tag of the reference.

Discussion

This functions retains a reference on the object with the specified tag (see also taggedRelease.)

Member Data

retainCount

private

mutable int retainCount;

Discussion

Number of references held on this instance.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19