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 #if IOKITSTATS
 168         friend class IOStatistics;
 169 #endif
 170
 171 private:
 172    /* Not to be included in headerdoc.
 173     *
 174     * @var retainCount Number of references held on this instance.
 175     */
 176     mutable int retainCount;
 177
 178 protected:
 179
 180 // xx-review: seems not to be used, should we deprecate?
 181
 182    /*!
 183     * @function release
 184     *
 185     * @abstract
 186     * Releases a reference to an object,
 187     * freeing it immediately if the reference count
 188     * drops below the specified threshold.
 189     *
 190     * @param freeWhen If decrementing the reference count makes it
 191     *                 >= <code>freeWhen</code>, the object is immediately freed.
 192     *
 193     * @discussion
 194     * If the receiver has <code>freeWhen</code> or fewer references
 195     * after its reference count is decremented,
 196     * it is immediately freed.
 197     *
 198     * This version of <code>release</code>
 199     * can be used to break certain retain cycles in object graphs.
 200     * In general, however, it should be avoided.
 201     */
 202     virtual void release(int freeWhen) const;
 203
 204    /*!
 205     * @function taggedRelease
 206     *
 207     * @abstract
 208     * Releases a tagged reference to an object,
 209     * freeing it immediately if the reference count
 210     * drops below the specified threshold.
 211     *
 212     * @param tag      Used for tracking collection references.
 213     * @param freeWhen If decrementing the reference count makes it
 214     *                 >= <code>freeWhen</code>, the object is immediately freed.
 215     *
 216     * @discussion
 217     * Kernel extensions should not use this function.
 218     * It is for use by OSCollection and subclasses to track
 219     * inclusion in collections.
 220     *
 221     * If the receiver has <code>freeWhen</code> or fewer references
 222     * after its reference count is decremented,
 223     * it is immediately freed.
 224     *
 225     * This version of <code>release</code>
 226     * can be used to break certain retain cycles in object graphs.
 227     * In general, however, it should be avoided.
 228     */
 229     virtual void taggedRelease(const void * tag, const int freeWhen) const;
 230
 231
 232    /*!
 233     * @function init
 234     *
 235     * @abstract
 236     * Initializes a newly-allocated object.
 237     *
 238     * @result
 239     * <code>true</code> on success, <code>false</code> on failure.
 240     *
 241     * @discussion
 242     * Classes derived from OSObject must override the primary init method
 243     * of their parent.
 244     * In general most implementations call
 245     * <code><i>super</i>::init()</code>
 246     * before doing local initialisation.
 247     * If the superclass call fails then return <code>false</code> immediately.
 248     * If the subclass encounters a failure then it should return <code>false</code>.
 249     */
 250     virtual bool init();
 251
 252
 253    /*!
 254     * @function free
 255     *
 256     * @abstract
 257     * Deallocates/releases resources held by the object.
 258     *
 259     * @discussion
 260     * Classes derived from OSObject should override this function
 261     * to deallocate or release all dynamic resources held by the instance,
 262     * then call the superclass's implementation.
 263     *
 264     * <b>Caution:<b>
 265     * <ol>
 266     * <li>You can not assume that you have completed initialization
 267     *     before <code>free</code> is called,
 268     *     so be very careful in your implementation.</li>
 269     * <li>OSObject's implementation performs the C++ <code>delete</code>
 270     *     of the instance, so be sure that you call the superclass
 271     *     implementation <i>last</i> in your implementation.</li>
 272     * <li><code>free</code> must not fail;
 273     *     all resources must be deallocated or released on completion.</li>
 274     * </ol>
 275     */
 276     virtual void free();
 277
 278
 279    /*!
 280     * @function operator delete
 281     *
 282     * @abstract
 283     * Frees the memory of the object itself.
 284     *
 285     * @param mem   A pointer to the object's memory.
 286     * @param size  The size of the object's block of memory.
 287     *
 288     * @discussion
 289     * Never use <code>delete</code> on objects derived from OSObject;
 290     * use
 291     * <code>@link
 292     * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 293     * release@/link</code>
 294     * instead.
 295     */
 296     static void operator delete(void * mem, size_t size);
 297
 298 public:
 299
 300    /*!
 301     * @function operator new
 302     *
 303     * @abstract
 304     * Allocates memory for an instance of the class.
 305     *
 306     * @param size The number of bytes to allocate
 307     *
 308     * @result
 309     * A pointer to block of memory if available, <code>NULL</code> otherwise.
 310     */
 311     static void * operator new(size_t size);
 312
 313
 314    /*!
 315     * @function getRetainCount
 316     *
 317     * @abstract
 318     * Returns the reference count of the object.
 319     *
 320     * @result
 321     * The reference count of the object.
 322     */
 323     virtual int getRetainCount() const;
 324
 325
 326    /*!
 327     * @function retain
 328     *
 329     * @abstract
 330     * Retains a reference to the object.
 331     *
 332     * @discussion
 333     * This function increments the reference count of the receiver by 1.
 334     * If you need to maintain a reference to an object
 335     * outside the context in which you received it,
 336     * you should always retain it immediately.
 337     */
 338     virtual void retain() const;
 339
 340
 341    /*!
 342     * @function release
 343     *
 344     * @abstract
 345     * Releases a reference to the object,
 346     * freeing it immediately if the reference count drops to zero.
 347     *
 348     * @discussion
 349     * This function decrements the reference count of the receiver by 1.
 350     * If the reference count drops to zero,
 351     * the object is immediately freed using
 352     * <code>@link
 353     * //apple_ref/cpp/instm/OSObject/free/virtualvoid/()
 354     * free@/link</code>.
 355     */
 356     virtual void release() const;
 357
 358
 359    /*!
 360     * @function taggedRetain
 361     *
 362     * @abstract
 363     * Retains a reference to the object with an optional
 364     * tag used for reference-tracking.
 365     *
 366     * @param tag      Used for tracking collection references.
 367     *
 368     * @discussion
 369     * Kernel extensions should not use this function.
 370     * It is for use by OSCollection and subclasses to track
 371     * inclusion in collections.
 372     *
 373     * If you need to maintain a reference to an object
 374     * outside the context in which you received it,
 375     * you should always retain it immediately.
 376     */
 377     virtual void taggedRetain(const void * tag = 0) const;
 378
 379
 380    /*!
 381     * @function taggedRelease
 382     *
 383     * @abstract
 384     * Releases a tagged reference to an object,
 385     * freeing it immediately if the reference count
 386     * drops to zero.
 387     *
 388     * @param tag      Used for tracking collection references.
 389     *
 390     * @discussion
 391     * Kernel extensions should not use this function.
 392     * It is for use by OSCollection and subclasses to track
 393     * inclusion in collections.
 394     */
 395     virtual void taggedRelease(const void * tag = 0) const;
 396     // 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
 397
 398
 399    /*!
 400     * @function serialize
 401     *
 402     * @abstract
 403     * Overridden by subclasses to archive the receiver into the provided
 404     * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
 405     *
 406     * @param serializer The OSSerialize object.
 407     *
 408     * @result
 409     * <code>true</code> if serialization succeeds, <code>false</code> if not.
 410     *
 411     * @discussion
 412     * OSObject's implementation writes a string indicating that
 413     * the class of the object receiving the function call
 414     * is not serializable.
 415     * Subclasses that can meaningfully encode themselves
 416     * in I/O Kit-style property list XML can override this function to do so.
 417     * See
 418     * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link
 419     * for more information.
 420     */
 421     virtual bool serialize(OSSerialize * serializer) const;
 422
 423     // Unused Padding
 424     OSMetaClassDeclareReservedUnused(OSObject,  0);
 425     OSMetaClassDeclareReservedUnused(OSObject,  1);
 426     OSMetaClassDeclareReservedUnused(OSObject,  2);
 427     OSMetaClassDeclareReservedUnused(OSObject,  3);
 428     OSMetaClassDeclareReservedUnused(OSObject,  4);
 429     OSMetaClassDeclareReservedUnused(OSObject,  5);
 430     OSMetaClassDeclareReservedUnused(OSObject,  6);
 431     OSMetaClassDeclareReservedUnused(OSObject,  7);
 432     OSMetaClassDeclareReservedUnused(OSObject,  8);
 433     OSMetaClassDeclareReservedUnused(OSObject,  9);
 434     OSMetaClassDeclareReservedUnused(OSObject, 10);
 435     OSMetaClassDeclareReservedUnused(OSObject, 11);
 436     OSMetaClassDeclareReservedUnused(OSObject, 12);
 437     OSMetaClassDeclareReservedUnused(OSObject, 13);
 438     OSMetaClassDeclareReservedUnused(OSObject, 14);
 439     OSMetaClassDeclareReservedUnused(OSObject, 15);
 440
 441 };
 442
 443 #endif /* !_LIBKERN_OSOBJECT_H */