docs/user/support/Referenceable.dox

   1 /*
   2  * Copyright 2015 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Adrien Destugues, pulkomandy@pulkomandy.tk
   7  *
   8  * Corresponds to:
   9  *              headers/os/support/Referenceable.h hrev48725
  10  *              src/kits/support/Referenceable.cpp hrev48725
  11  */
  12
  13
  14 /*!
  15         \file Referenceable.h
  16         \ingroup support
  17         \ingroup libbe
  18         \brief Provides the BReferenceable interface and declares the BReferenceable
  19                and BReference classes.
  20 */
  21
  22
  23 /*!
  24         \class BReferenceable
  25         \ingroup support
  26         \ingroup libbe
  27         \brief Implementation of reference-counted memory management.
  28
  29         The C++ language provides two main ways of allocating objects: on the stack,
  30         and on the heap. Objects created on the heap must be managed by the
  31         application and deleted when they are not needed. Objects allocated on the
  32         stack have a lifetime limited to the execution of the block they are
  33         declared in.
  34
  35         This approach is simple, but in some cases it can become quite difficult to
  36         track ownership and lifetime of objects. The BReferenceable class allows to
  37         implement reference counting, which allows a partially automated memory
  38         management and some safety checks. It can also be used to implement pools
  39         of reusable objects.
  40
  41         As the name implies, reference counting consists of keeping track, inside an
  42         object, of how much references there are to it in the running application.
  43         When the object is not referenced anymore, it can't be reached or used from
  44         other parts of the application, so it is safe to delete or recycle the
  45         object.
  46
  47         To use reference counting for a particular class, you make it inherit
  48         BReferenceable. This provides all the support for reference counting.
  49         Objects are created as usual, on the stack or using the new operator.
  50
  51         The object can then be referenced from other places. Each time a reference
  52         to it is kept, the owner of the reference should call AcquireReference.
  53         When the reference is not needed, it should call ReleaseReference.
  54
  55         \since Haiku R1
  56 */
  57
  58
  59 /*!
  60         \fn BReferenceable::BReferenceable()
  61         \brief Initialize the object with a reference count of 1.
  62
  63         The creator of the object is assumed to owns the first reference to it.
  64 */
  65
  66
  67 /*!
  68         \fn BReferenceable::~BReferenceable()
  69         \brief Destructor.
  70
  71         The destructor should not be called directly, as the object is destructed
  72         automatically when the last reference is released. This destructor is
  73         public because you may still need to destroy the objects in the case where
  74         LastReferenceReleased is overriden and you handle object destruction in
  75         some other way.
  76
  77         In debug mode, the destructor checks that no references to the object are
  78         still held. If the object was allocated on the stack, it allows exactly one
  79         reference to be kept, which makes it possible to allocate BReferenceable
  80         on the stack without needing to release the single reference to it.
  81 */
  82
  83
  84 /*!
  85         \fn int32 BReferenceable::AcquireReference()
  86         \brief Acquire a reference to the object.
  87         \returns the previous reference count
  88
  89         If the reference count was previously 0, this will call
  90         FirstReferenceAcquired.
  91 */
  92
  93
  94 /*!
  95         \fn int32 BReferenceable::ReleaseReference()
  96         \brief Release a reference to the object.
  97         \returns the previous reference count
  98
  99         If the reference count was previously 1 (and is now 0), this will call
 100         LastReferenceReleased.
 101 */
 102
 103
 104 /*!
 105         \fn int32 BReferenceable::CountReferences()
 106         \brief Return the number of references to the object.
 107         \returns the reference count.
 108 */
 109
 110
 111 /*!
 112         \fn void BReferenceable::FirstReferenceAcquired()
 113         \brief Called when the first reference to the object is reacquired.
 114
 115         The default implementation does nothing. This method can be overriden to
 116         implement reinitialization of the object, when using BReferenceable to
 117         keep track of a pool of reusable objects.
 118
 119         In this use case, the objects are created (at initialization or lazily on an
 120         as-needed basis) and stored in a pool. When an object is needed, if there
 121         is an unused one waiting in the pool, it is reused instead of creating a
 122         new one. Once a reference to it is acquired, this method is called and the
 123         object can initialize itself to a clean state.
 124
 125         \warning This is currently not called when the object is first created, but
 126         only on subsequent reuses.
 127 */
 128
 129
 130 /*!
 131         \fn void BReferenceable::LastReferenceReleased()
 132         \brief Called when the last reference to the object is released.
 133
 134         This function is called when the object is not referenced anymore. The
 135         default implementation deletes the object using the delete operator.
 136
 137         This behavior can be overriden. For example, to implement an object pool,
 138         this method would not delete the object, but instead put it back in the
 139         free object pool, ready for reuse at a later point.
 140 */
 141
 142
 143
 144
 145 /*!
 146         \class BReference
 147         \ingroup support
 148         \ingroup libbe
 149         \brief A reference to a BReferenceable object.
 150
 151         BReference simplifies the use of BReferenceable and makes it more
 152         transparent. It automatically acquires and release references to the pointed
 153         objects. It provides an API similar to a standard C++ pointer, allowing use
 154         of assignment and comparison operators and direct access to the object with
 155         -> and *.
 156 */
 157
 158
 159 /*!
 160         \fn BReference::BReference()
 161         \brief Creates a reference without initializing it
 162
 163         An uninitialized references behaves similarly to a NULL pointer.
 164 */
 165
 166
 167 /*!
 168         \fn BReference::BReference(Type*, bool)
 169         \brief Creates and initialize a reference
 170
 171         The reference is set to the pointed object. If the parameter is set to
 172         true, the reference count is not incremented, this should only be used when
 173         referencing a freshly constructed object.
 174 */
 175
 176
 177 /*!
 178         \fn BReference::BReference(const BReference& other)
 179         \brief Copy constructor
 180
 181         The reference is set to the same object as the source. The reference count
 182         of the target object is incremented.
 183 */
 184
 185
 186 /*!
 187         \fn BReference::~BReference
 188         \brief Destructor.
 189
 190         The reference count of the target object is decremented.
 191 */
 192
 193
 194 /*!
 195         \fn void BReference::SetTo(Type*, bool)
 196         \brief Sets a new target for the reference.
 197
 198         The reference to the previously targetted object is released.
 199         A reference to the new object is acquired only if \p alreadyHasReference
 200         is false.
 201 */
 202
 203
 204 /*!
 205         \fn void BReference::Unset()
 206         \brief Unsets the reference.
 207
 208         The targetted object is released. The reference is unset and can't be used
 209         to access it anymore.
 210 */
 211
 212
 213 /*!
 214         \fn ConstType* BReference::Get() const
 215         \brief Get the target object
 216         \returns a raw pointer to the target object.
 217 */
 218
 219
 220 /*!
 221         \fn ConstType* BReference::Detach() const
 222         \brief Detach the pointed object from the reference
 223         \returns a raw pointer to the target object.
 224
 225         This returns the pointed object and unsets the reference, without
 226         decrementing the object reference count. It is used to transfer ownership of
 227         the reference to something else.
 228 */