libkern/libkern/c++/OSObject.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License.  The rights granted to you under the
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30 /*
  31 Copyright (c) 1998 Apple Computer, Inc.  All rights reserved.
  32 HISTORY
  33     1998-10-30  Godfrey van der Linden(gvdl)
  34         Created
  35 */
  36 #ifndef _LIBKERN_OSOBJECT_H
  37 #define _LIBKERN_OSOBJECT_H
  38
  39 #include <libkern/c++/OSMetaClass.h>
  40
  41 class OSSymbol;
  42 class OSString;
  43 /*!
  44     @class OSObject : OSMetaClassBase
  45     @abstract The root base class for Mac OS X kernel and just generally all-round useful class to have around.
  46     @discussion
  47 Defines the minimum functionality that an object can expect.  Implements reference counting, type safe object casting, allocation primitives & serialisation among other functionality.  This object is an abstract base class and can not be copied, nor can it be constructed by itself.
  48
  49 <br><br> Construction <br><br>
  50
  51 As Mac OS X's C++ is based upon Embedded C++ we have a problem with the typical C++ method of using constructors.  Embedded C++ does not allow exceptions.  This means that the standard constructors can not report a failure.  Well obviously initialisation 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 initialisation is the object has exactly one reference after creation.  Once the new is called the client MUST call init and check it's return value.  If the init call fails then the object MUST be immediately released.  IOKit usually implements factory methods to make construction a one step process for clients.
  52
  53 <br><br>Reference Counting<br><br>
  54
  55 OSObject provides reference counting services using the $link retain(), $link release(), $link release(int when) and $link 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.
  56 <br>
  57 In general a subclass is expected to only override $link free().  It may also choose to override release() if the object has a circular retain count, see $link release(int when);
  58
  59 <br><br>Runtime Type Information System<br><br>
  60
  61 The Mac OS X C++ implements a basic runtime type information system using meta class information and a number of macros, $link OSDynamicCast, $link OSTypeID, $link OSTypeIDInst, $link OSCheckTypeInst and $link OSMetaClass.
  62 */
  63 class OSObject : public OSMetaClassBase
  64 {
  65     OSDeclareAbstractStructors(OSObject)
  66
  67 private:
  68 /*! @var retainCount Number of references held on this instance. */
  69     mutable int retainCount;
  70
  71 protected:
  72
  73 /*! @function release
  74     @abstract untagged release(when) mechansim.
  75     @param when Pass through to taggedRelease. */
  76     virtual void release(int when) const;
  77
  78 /*! @function taggedRelease
  79     @abstract Primary implementation of the tagged release mechanism.
  80     @discussion  If $link retainCount <= the when argument then call $link free().  This indirect implementation of $link release allows the developer to break reference circularity.  An example of this sort of problem is a parent/child mutual reference, either the parent or child can implement: void taggedRelease(tag) { taggedRelease(tag, 2); } thus breaking the cirularity.
  81     @param when If retainCount == when then call free(). */
  82     virtual void taggedRelease(const void *tag, const int when) const;
  83
  84 /*! @function init
  85     @abstract Mac OS X kernel's primary mechanism for constructing objects.
  86     @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 initialisation, if the parent fails then return false immediately.  If you have a failure during you local initialisation then return false.
  87     @result OSObject::init Always returns true, but subclasses will return false on init failure.
  88 */
  89     virtual bool init();
  90
  91 /*! @function free
  92     @abstract The last reference is gone so clean up your resources.
  93     @discussion Release all resources held by the object, then call your parent's free().
  94
  95 <br><br>Caution:
  96 <br>1> You can not assume that you have completed initialization before your free is called, so be very careful in your implementation.
  97 <br>2> The implementation is OSObject::free() { delete this; } so do not call super::free() until just before you return.
  98 <br>3> Free is not allowed to fail all resource must be released on completion. */
  99     virtual void free();
 100
 101 /*! @function operator delete
 102     @abstract Release the 'operator new'ed memory.
 103     @discussion Never attempt to delete an object that inherits from OSObject directly use $link release().
 104     @param mem pointer to block of memory
 105     @param size size of block of memory
 106 */
 107     static void operator delete(void *mem, size_t size);
 108
 109 public:
 110
 111 /*! @function operator new
 112     @abstract Allocator for all objects that inherit from OSObject
 113     @param size number of bytes to allocate
 114     @result returns pointer to block of memory if available, 0 otherwise.
 115 */
 116     static void *operator new(size_t size);
 117
 118 /*! @function getRetainCount
 119     @abstract How many times has this object been retained?
 120     @result Current retain count
 121 */
 122     virtual int getRetainCount() const;
 123
 124 /*! @function retain
 125     @abstract Retain a reference in this object.
 126     @discussion Takes a reference that is NULL tagged.  See taggedRetain().
 127 */
 128     virtual void retain() const;
 129
 130 /*! @function release
 131     @abstract Release a reference to this object
 132     @discussion Removes a reference that is NULL tagged.  See taggedRelease().
 133 */
 134     virtual void release() const;
 135
 136 /*! @function taggedRetain
 137     @abstract Retain a tagged reference in this object.
 138     @param tag Retain a reference on this object with this tag, see taggedRelease.
 139 */
 140     virtual void taggedRetain(const void *tag = 0) const;
 141
 142 /*! @function taggedRelease
 143     @abstract Release a tagged reference to this object
 144     @param tag Remove a reference on this object with this tag, if an attempt is made to remove a reference that isn't associated with this tag the kernel will panic immediately.
 145 */
 146     virtual void taggedRelease(const void *tag = 0) const;
 147
 148 /*! @function serialize
 149     @abstract
 150     @discussion
 151     @param s
 152     @result
 153 */
 154     virtual bool serialize(OSSerialize *s) const;
 155
 156     // Unused Padding
 157     OSMetaClassDeclareReservedUnused(OSObject,  0);
 158     OSMetaClassDeclareReservedUnused(OSObject,  1);
 159     OSMetaClassDeclareReservedUnused(OSObject,  2);
 160     OSMetaClassDeclareReservedUnused(OSObject,  3);
 161     OSMetaClassDeclareReservedUnused(OSObject,  4);
 162     OSMetaClassDeclareReservedUnused(OSObject,  5);
 163     OSMetaClassDeclareReservedUnused(OSObject,  6);
 164     OSMetaClassDeclareReservedUnused(OSObject,  7);
 165     OSMetaClassDeclareReservedUnused(OSObject,  8);
 166     OSMetaClassDeclareReservedUnused(OSObject,  9);
 167     OSMetaClassDeclareReservedUnused(OSObject, 10);
 168     OSMetaClassDeclareReservedUnused(OSObject, 11);
 169     OSMetaClassDeclareReservedUnused(OSObject, 12);
 170     OSMetaClassDeclareReservedUnused(OSObject, 13);
 171     OSMetaClassDeclareReservedUnused(OSObject, 14);
 172     OSMetaClassDeclareReservedUnused(OSObject, 15);
 173     OSMetaClassDeclareReservedUnused(OSObject, 16);
 174     OSMetaClassDeclareReservedUnused(OSObject, 17);
 175     OSMetaClassDeclareReservedUnused(OSObject, 18);
 176     OSMetaClassDeclareReservedUnused(OSObject, 19);
 177     OSMetaClassDeclareReservedUnused(OSObject, 20);
 178     OSMetaClassDeclareReservedUnused(OSObject, 21);
 179     OSMetaClassDeclareReservedUnused(OSObject, 22);
 180     OSMetaClassDeclareReservedUnused(OSObject, 23);
 181     OSMetaClassDeclareReservedUnused(OSObject, 24);
 182     OSMetaClassDeclareReservedUnused(OSObject, 25);
 183     OSMetaClassDeclareReservedUnused(OSObject, 26);
 184     OSMetaClassDeclareReservedUnused(OSObject, 27);
 185     OSMetaClassDeclareReservedUnused(OSObject, 28);
 186     OSMetaClassDeclareReservedUnused(OSObject, 29);
 187     OSMetaClassDeclareReservedUnused(OSObject, 30);
 188     OSMetaClassDeclareReservedUnused(OSObject, 31);
 189 };
 190
 191 #endif /* !_LIBKERN_OSOBJECT_H */