libkern/libkern/c++/OSObject.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_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 License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /*
  29 Copyright (c) 1998 Apple Computer, Inc.  All rights reserved.
  30 HISTORY
  31     1998-10-30  Godfrey van der Linden(gvdl)
  32     Created
  33 */
  34 #ifndef _LIBKERN_OSOBJECT_H
  35 #define _LIBKERN_OSOBJECT_H
  36
  37 #include <libkern/c++/OSMetaClass.h>
  38
  39 class OSSymbol;
  40 class OSString;
  41
  42
  43 /*!
  44  * @header
  45  *
  46  * @abstract
  47  * This header declares the OSObject class,
  48  * which is the concrete root of the Libkern C++ class hierarchy.
  49  */
  50
  51
  52 /*!
  53  * @class OSObject
  54  *
  55  * @abstract
  56  * OSObject is the concrete root class
  57  * of the Libkern and I/O Kit C++ class hierarchy.
  58  *
  59  * @discussion
  60  * OSObject defines the minimal functionality
  61  * required of Libkern and I/O Kit C++ classes:
  62  * tie-in to the run-time type information facility,
  63  * the dynamic allocation/initialization paradigm,
  64  * and reference counting.
  65  * While kernel extensions are free to use their own C++ classes internally,
  66  * any interaction they have with Libkern or the I/O Kit will require
  67  * classes ultimately derived from OSObject.
  68  *
  69  * <b>Run-Time Type Information</b>
  70  *
  71  * OSObject is derived from the abstract root class
  72  * @link //apple_ref/doc/class/OSMetaClassBase OSMetaClassBase@/link,
  73  * which declares (and defines many of) the primitives
  74  * on which the run-time type information facility is based.
  75  * A parallel inheritance hierarchy of metaclass objects
  76  * provides run-time introspection, including access to class names,
  77  * inheritance, and safe type-casting.
  78  * See @link //apple_ref/doc/class/OSMetaClass OSMetaClass@/link
  79  * for more information.
  80  *
  81  * <b>Dynamic Allocation/Initialization</b>
  82  *
  83  * The kernel-resident C++ runtime does not support exceptions,
  84  * so Libkern classes cannot use standard C++ object
  85  * constructors and destructors,
  86  * which use exceptions to report errors.
  87  * To support error-handling during instance creation, then,
  88  * OSObject separates object allocation from initialization.
  89  * You can create a new OSObject-derived instance
  90  * with the <code>new</code> operator,
  91  * but this does nothing more than allocate memory
  92  * and initialize the reference count to 1.
  93  * Following this, you must call a designated initialization function
  94  * and check its <code>bool</code> return value.
  95  * If the initialization fails,
  96  * you must immediately call
  97  * <code>@link
  98  * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
  99  * release@/link</code>
 100  * on the instance and handle the failure in whatever way is appropriate.
 101  * Many Libkern and I/O Kit classes define static instance-creation functions
 102  * (beginning with the word "with")
 103  * to make construction a one-step process for clients.
 104  *
 105  * <b>Reference Counting</b>
 106  *
 107  * OSObject provides reference counting services using the
 108  * <code>@link
 109  * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
 110  * retain@/link</code>,
 111  * <code>@link
 112  * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 113  * release()@/link</code>,
 114  * <code>@link
 115  * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int)
 116  * release(int freeWhen)@/link</code>
 117  * and
 118  *<code> @link
 119  * //apple_ref/cpp/instm/OSObject/free/virtualvoid/()
 120  * free@/link</code>
 121  * functions.
 122  * The public interface to the reference counting is
 123  * <code>@link
 124  * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
 125  * retain@/link</code>,
 126  * and
 127  * <code>@link
 128  * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 129  * release@/link</code>;
 130  * <code>@link
 131  * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int)
 132  * release(int freeWhen)@/link</code>
 133  * is provided
 134  * for objects that have internal retain cycles.
 135  *
 136  * In general, a subclass is expected to only override
 137  * <code>@link
 138  * //apple_ref/cpp/instm/OSObject/free/virtualvoid/()
 139  * free@/link</code>.
 140  * It may also choose to override
 141  * <code>@link
 142  * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int)
 143  * release(int freeWhen)@/link</code>
 144  * if the object has a circular retain count, as noted above.
 145  *
 146  * <b>Use Restrictions</b>
 147  *
 148  * With very few exceptions in the I/O Kit, all Libkern-based C++
 149  * classes, functions, and macros are <b>unsafe</b>
 150  * to use in a primary interrupt context.
 151  * Consult the I/O Kit documentation related to primary interrupts
 152  * for more information.
 153  *
 154  * <b>Concurrency Protection</b>
 155  *
 156  * The basic features of OSObject are thread-safe.
 157  * Most Libkern subclasses are not, and require locking or other protection
 158  * if instances are shared between threads.
 159  * I/O Kit driver objects are either designed for use within thread-safe contexts
 160  * or designed to inherently be thread-safe.
 161  * Always check the individual class documentation to see what
 162  * steps are necessary for concurrent use of instances.
 163  */
 164 class OSObject : public OSMetaClassBase
 165 {
 166     OSDeclareAbstractStructors(OSObject)
 167
 168 private:
 169    /* Not to be included in headerdoc.
 170     *
 171     * @var retainCount Number of references held on this instance.
 172     */
 173     mutable int retainCount;
 174
 175 protected:
 176
 177 // xx-review: seems not to be used, should we deprecate?
 178
 179    /*!
 180     * @function release
 181     *
 182     * @abstract
 183     * Releases a reference to an object,
 184     * freeing it immediately if the reference count
 185     * drops below the specified threshold.
 186     *
 187     * @param freeWhen If decrementing the reference count makes it
 188     *                 >= <code>freeWhen</code>, the object is immediately freed.
 189     *
 190     * @discussion
 191     * If the receiver has <code>freeWhen</code> or fewer references
 192     * after its reference count is decremented,
 193     * it is immediately freed.
 194     *
 195     * This version of <code>release</code>
 196     * can be used to break certain retain cycles in object graphs.
 197     * In general, however, it should be avoided.
 198     */
 199     virtual void release(int freeWhen) const;
 200
 201    /*!
 202     * @function taggedRelease
 203     *
 204     * @abstract
 205     * Releases a tagged reference to an object,
 206     * freeing it immediately if the reference count
 207     * drops below the specified threshold.
 208     *
 209     * @param tag      Used for tracking collection references.
 210     * @param freeWhen If decrementing the reference count makes it
 211     *                 >= <code>freeWhen</code>, the object is immediately freed.
 212     *
 213     * @discussion
 214     * Kernel extensions should not use this function.
 215     * It is for use by OSCollection and subclasses to track
 216     * inclusion in collections.
 217     *
 218     * If the receiver has <code>freeWhen</code> or fewer references
 219     * after its reference count is decremented,
 220     * it is immediately freed.
 221     *
 222     * This version of <code>release</code>
 223     * can be used to break certain retain cycles in object graphs.
 224     * In general, however, it should be avoided.
 225     */
 226     virtual void taggedRelease(const void * tag, const int freeWhen) const;
 227
 228
 229    /*!
 230     * @function init
 231     *
 232     * @abstract
 233     * Initializes a newly-allocated object.
 234     *
 235     * @result
 236     * <code>true</code> on success, <code>false</code> on failure.
 237     *
 238     * @discussion
 239     * Classes derived from OSObject must override the primary init method
 240     * of their parent.
 241     * In general most implementations call
 242     * <code><i>super</i>::init()</code>
 243     * before doing local initialisation.
 244     * If the superclass call fails then return <code>false</code> immediately.
 245     * If the subclass encounters a failure then it should return <code>false</code>.
 246     */
 247     virtual bool init();
 248
 249
 250    /*!
 251     * @function free
 252     *
 253     * @abstract
 254     * Deallocates/releases resources held by the object.
 255     *
 256     * @discussion
 257     * Classes derived from OSObject should override this function
 258     * to deallocate or release all dynamic resources held by the instance,
 259     * then call the superclass's implementation.
 260     *
 261     * <b>Caution:<b>
 262     * <ol>
 263     * <li>You can not assume that you have completed initialization
 264     *     before <code>free</code> is called,
 265     *     so be very careful in your implementation.</li>
 266     * <li>OSObject's implementation performs the C++ <code>delete</code>
 267     *     of the instance, so be sure that you call the superclass
 268     *     implementation <i>last</i> in your implementation.</li>
 269     * <li><code>free</code> must not fail;
 270     *     all resources must be deallocated or released on completion.</li>
 271     * </ol>
 272     */
 273     virtual void free();
 274
 275
 276    /*!
 277     * @function operator delete
 278     *
 279     * @abstract
 280     * Frees the memory of the object itself.
 281     *
 282     * @param mem   A pointer to the object's memory.
 283     * @param size  The size of the object's block of memory.
 284     *
 285     * @discussion
 286     * Never use <code>delete</code> on objects derived from OSObject;
 287     * use
 288     * <code>@link
 289     * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 290     * release@/link</code>
 291     * instead.
 292     */
 293     static void operator delete(void * mem, size_t size);
 294
 295 public:
 296
 297    /*!
 298     * @function operator new
 299     *
 300     * @abstract
 301     * Allocates memory for an instance of the class.
 302     *
 303     * @param size The number of bytes to allocate
 304     *
 305     * @result
 306     * A pointer to block of memory if available, <code>NULL</code> otherwise.
 307     */
 308     static void * operator new(size_t size);
 309
 310
 311    /*!
 312     * @function getRetainCount
 313     *
 314     * @abstract
 315     * Returns the reference count of the object.
 316     *
 317     * @result
 318     * The reference count of the object.
 319     */
 320     virtual int getRetainCount() const;
 321
 322
 323    /*!
 324     * @function retain
 325     *
 326     * @abstract
 327     * Retains a reference to the object.
 328     *
 329     * @discussion
 330     * This function increments the reference count of the receiver by 1.
 331     * If you need to maintain a reference to an object
 332     * outside the context in which you received it,
 333     * you should always retain it immediately.
 334     */
 335     virtual void retain() const;
 336
 337
 338    /*!
 339     * @function release
 340     *
 341     * @abstract
 342     * Releases a reference to the object,
 343     * freeing it immediately if the reference count drops to zero.
 344     *
 345     * @discussion
 346     * This function decrements the reference count of the receiver by 1.
 347     * If the reference count drops to zero,
 348     * the object is immediately freed using
 349     * <code>@link
 350     * //apple_ref/cpp/instm/OSObject/free/virtualvoid/()
 351     * free@/link</code>.
 352     */
 353     virtual void release() const;
 354
 355
 356    /*!
 357     * @function taggedRetain
 358     *
 359     * @abstract
 360     * Retains a reference to the object with an optional
 361     * tag used for reference-tracking.
 362     *
 363     * @param tag      Used for tracking collection references.
 364     *
 365     * @discussion
 366     * Kernel extensions should not use this function.
 367     * It is for use by OSCollection and subclasses to track
 368     * inclusion in collections.
 369     *
 370     * If you need to maintain a reference to an object
 371     * outside the context in which you received it,
 372     * you should always retain it immediately.
 373     */
 374     virtual void taggedRetain(const void * tag = 0) const;
 375
 376
 377    /*!
 378     * @function taggedRelease
 379     *
 380     * @abstract
 381     * Releases a tagged reference to an object,
 382     * freeing it immediately if the reference count
 383     * drops to zero.
 384     *
 385     * @param tag      Used for tracking collection references.
 386     *
 387     * @discussion
 388     * Kernel extensions should not use this function.
 389     * It is for use by OSCollection and subclasses to track
 390     * inclusion in collections.
 391     */
 392     virtual void taggedRelease(const void * tag = 0) const;
 393     // xx-review: used to say, "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", but I don't see that in the implementation
 394
 395
 396    /*!
 397     * @function serialize
 398     *
 399     * @abstract
 400     * Overridden by subclasses to archive the receiver into the provided
 401     * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
 402     *
 403     * @param serializer The OSSerialize object.
 404     *
 405     * @result
 406     * <code>true</code> if serialization succeeds, <code>false</code> if not.
 407     *
 408     * @discussion
 409     * OSObject's implementation writes a string indicating that
 410     * the class of the object receiving the function call
 411     * is not serializable.
 412     * Subclasses that can meaningfully encode themselves
 413     * in I/O Kit-style property list XML can override this function to do so.
 414     * See
 415     * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link
 416     * for more information.
 417     */
 418     virtual bool serialize(OSSerialize * serializer) const;
 419
 420     // Unused Padding
 421     OSMetaClassDeclareReservedUnused(OSObject,  0);
 422     OSMetaClassDeclareReservedUnused(OSObject,  1);
 423     OSMetaClassDeclareReservedUnused(OSObject,  2);
 424     OSMetaClassDeclareReservedUnused(OSObject,  3);
 425     OSMetaClassDeclareReservedUnused(OSObject,  4);
 426     OSMetaClassDeclareReservedUnused(OSObject,  5);
 427     OSMetaClassDeclareReservedUnused(OSObject,  6);
 428     OSMetaClassDeclareReservedUnused(OSObject,  7);
 429     OSMetaClassDeclareReservedUnused(OSObject,  8);
 430     OSMetaClassDeclareReservedUnused(OSObject,  9);
 431     OSMetaClassDeclareReservedUnused(OSObject, 10);
 432     OSMetaClassDeclareReservedUnused(OSObject, 11);
 433     OSMetaClassDeclareReservedUnused(OSObject, 12);
 434     OSMetaClassDeclareReservedUnused(OSObject, 13);
 435     OSMetaClassDeclareReservedUnused(OSObject, 14);
 436     OSMetaClassDeclareReservedUnused(OSObject, 15);
 437
 438 #ifdef __ppc__
 439     OSMetaClassDeclareReservedUnused(OSObject, 16);
 440     OSMetaClassDeclareReservedUnused(OSObject, 17);
 441     OSMetaClassDeclareReservedUnused(OSObject, 18);
 442     OSMetaClassDeclareReservedUnused(OSObject, 19);
 443     OSMetaClassDeclareReservedUnused(OSObject, 20);
 444     OSMetaClassDeclareReservedUnused(OSObject, 21);
 445     OSMetaClassDeclareReservedUnused(OSObject, 22);
 446     OSMetaClassDeclareReservedUnused(OSObject, 23);
 447     OSMetaClassDeclareReservedUnused(OSObject, 24);
 448     OSMetaClassDeclareReservedUnused(OSObject, 25);
 449     OSMetaClassDeclareReservedUnused(OSObject, 26);
 450     OSMetaClassDeclareReservedUnused(OSObject, 27);
 451     OSMetaClassDeclareReservedUnused(OSObject, 28);
 452     OSMetaClassDeclareReservedUnused(OSObject, 29);
 453     OSMetaClassDeclareReservedUnused(OSObject, 30);
 454     OSMetaClassDeclareReservedUnused(OSObject, 31);
 455 #endif
 456 };
 457
 458 #endif /* !_LIBKERN_OSOBJECT_H */