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*/ 229