libkern/libkern/c++/OSObject.h

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