[5804] | 1 | /* |
---|
| 2 | * ORXONOX - the hottest 3D action shooter ever to exist |
---|
| 3 | * > www.orxonox.net < |
---|
| 4 | * |
---|
| 5 | * |
---|
| 6 | * License notice: |
---|
| 7 | * |
---|
| 8 | * This program is free software; you can redistribute it and/or |
---|
| 9 | * modify it under the terms of the GNU General Public License |
---|
| 10 | * as published by the Free Software Foundation; either version 2 |
---|
| 11 | * of the License, or (at your option) any later version. |
---|
| 12 | * |
---|
| 13 | * This program is distributed in the hope that it will be useful, |
---|
| 14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
| 15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
---|
| 16 | * GNU General Public License for more details. |
---|
| 17 | * |
---|
| 18 | * You should have received a copy of the GNU General Public License |
---|
| 19 | * along with this program; if not, write to the Free Software |
---|
| 20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
---|
| 21 | * |
---|
| 22 | * Author: |
---|
| 23 | * Fabian 'x3n' Landau |
---|
| 24 | * Co-authors: |
---|
| 25 | * ... |
---|
| 26 | * |
---|
| 27 | */ |
---|
| 28 | |
---|
| 29 | // Inspired by boost::intrusive_ptr by Peter Dimov |
---|
| 30 | |
---|
[7401] | 31 | /** |
---|
| 32 | @defgroup SmartPtr SmartPtr<T> and WeakPtr<T> |
---|
| 33 | @ingroup Object |
---|
| 34 | */ |
---|
| 35 | |
---|
| 36 | /** |
---|
| 37 | @file |
---|
| 38 | @ingroup Object SmartPtr |
---|
| 39 | @brief Definition of SmartPtr<T>, wraps a pointer to an object and keeps it alive. |
---|
| 40 | |
---|
| 41 | @anchor SmartPtrExample |
---|
| 42 | |
---|
| 43 | orxonox::SmartPtr is an implementation of a smart pointer - it wraps a pointer to an |
---|
| 44 | object and keeps this object alive until no SmartPtr points to this object anymore. |
---|
| 45 | In contrast to orxonox::SharedPtr, SmartPtr works only with classes that are derived |
---|
[9571] | 46 | from orxonox::Destroyable, because it's an intrusive implementation, meaning the |
---|
[7401] | 47 | reference counter is stored in the object itself. |
---|
| 48 | |
---|
| 49 | It's possible to use normal pointers and smart pointers to an object simultaneously. |
---|
| 50 | You don't have to use SmartPtr all the time, you can create a SmartPtr for an object |
---|
| 51 | at any time and also convert it back to a normal pointer if you like. This is possible |
---|
| 52 | because the reference counter is stored in the object itself and not in SmartPtr (in |
---|
| 53 | contrast to SharedPtr). |
---|
| 54 | |
---|
| 55 | @b Important: If you want to delete an object, you must not use @c delete @c object but |
---|
| 56 | rather @c object->destroy(). This function will check if there are smart pointers |
---|
| 57 | pointing to the object. If yes, the object will be kept alive until all smart pointes |
---|
| 58 | are destroyed. If no, the object is deleted instantly. |
---|
| 59 | |
---|
| 60 | If all smart pointers that point to an object are destroyed, but you never called |
---|
| 61 | @c object->destroy() before, the object will not be deleted! All a SmartPtr will do |
---|
| 62 | is to really just keep an object alive, but it will not delete it automatically |
---|
| 63 | unless you tried to destroy it before. |
---|
| 64 | |
---|
| 65 | Example: |
---|
| 66 | @code |
---|
| 67 | class MyClass // class declaration |
---|
| 68 | { |
---|
| 69 | public: |
---|
| 70 | void setObject(OtherClass* object) // passes a normal pointer which will be stored in a SmartPtr |
---|
| 71 | { this->object_ = object; } |
---|
| 72 | |
---|
| 73 | OtherClass* getObject() const // converts the SmartPtr to a normal pointer and returns it |
---|
| 74 | { return this->object_; } |
---|
| 75 | |
---|
| 76 | private: |
---|
| 77 | SmartPtr<OtherClass> object_; // a pointer to an instance of OtherClass is stored in a SmartPtr |
---|
| 78 | }; |
---|
| 79 | @endcode |
---|
[9571] | 80 | In this example we assume that OtherClass is a child of Destroyable. We don't care |
---|
[7401] | 81 | about the inheritance of MyClass though. |
---|
| 82 | |
---|
| 83 | Now we create an instance of MyClass and assign a pointer to an instance of OtherClass: |
---|
| 84 | @code |
---|
| 85 | MyClass* myclass = new MyClass(); // create an instance of MyClass |
---|
| 86 | OtherClass* object = new OtherClass(); // create an instance of OtherClass |
---|
| 87 | myclass->setObject(object); // the object is now stored in a SmartPtr inside myclass |
---|
| 88 | |
---|
| 89 | object->destroy(); // we try to destroy object, but there's still a SmartPtr pointing at it. |
---|
| 90 | |
---|
| 91 | # object still exists at this point (because a SmartPtr points at it) |
---|
| 92 | |
---|
| 93 | delete myclass; // now we delete myclass, which also destroys the SmartPtr |
---|
| 94 | |
---|
| 95 | # object doesn't exist anymore (because the SmartPtr is now destroyed) |
---|
| 96 | @endcode |
---|
| 97 | |
---|
| 98 | Now we look at the same example, but we first delete myclass, then destroy object: |
---|
| 99 | @code |
---|
| 100 | MyClass* myclass = new MyClass(); // create an instance of MyClass |
---|
| 101 | OtherClass* object = new OtherClass(); // create an instance of OtherClass |
---|
| 102 | myclass->setObject(object); // the object is now stored in a SmartPtr inside myclass |
---|
| 103 | |
---|
| 104 | delete myclass; // we delete myclass, which also destroys the SmartPtr |
---|
| 105 | |
---|
| 106 | # object still exists at this point (because destroy() was not called yet) |
---|
| 107 | |
---|
| 108 | object->destroy(); // now we try to destroy object, which works instantly |
---|
| 109 | |
---|
| 110 | # object doesn't exist anymore (because we just destroyed it) |
---|
| 111 | @endcode |
---|
| 112 | |
---|
| 113 | Note that in any case @c object->destroy() has to be called to delete the object. |
---|
| 114 | However if a SmartPtr points at it, the destruction is delayed until all SmartPtr |
---|
| 115 | are destroyed. |
---|
| 116 | */ |
---|
| 117 | |
---|
[5804] | 118 | #ifndef _SmartPtr_H__ |
---|
| 119 | #define _SmartPtr_H__ |
---|
| 120 | |
---|
[9557] | 121 | #include "core/CorePrereqs.h" |
---|
[5804] | 122 | |
---|
[5807] | 123 | #include <cassert> |
---|
[5823] | 124 | |
---|
[9571] | 125 | #include "core/object/Destroyable.h" |
---|
[5823] | 126 | #include "WeakPtr.h" |
---|
[5804] | 127 | |
---|
| 128 | namespace orxonox |
---|
| 129 | { |
---|
[7401] | 130 | /** |
---|
| 131 | @brief A smart pointer which wraps a pointer to an object and keeps this object alive as long as the smart pointer exists. |
---|
| 132 | |
---|
| 133 | @see See @ref SmartPtrExample "this description" for more information and an example. |
---|
| 134 | */ |
---|
[5804] | 135 | template <class T> |
---|
| 136 | class SmartPtr |
---|
| 137 | { |
---|
| 138 | public: |
---|
[7401] | 139 | /// Constructor: Initializes the smart pointer with a null pointer. |
---|
[5805] | 140 | inline SmartPtr() : pointer_(0), base_(0) |
---|
[5804] | 141 | { |
---|
| 142 | } |
---|
| 143 | |
---|
[7401] | 144 | /// Constructor: Initializes the smart pointer with a pointer to an object. @param pointer The pointer @param bAddRef If true, the reference counter is increased. Don't set this to false unless you know exactly what you're doing! (for example to avoid circular references if the @c this pointer of the possessing object is stored) |
---|
[5805] | 145 | inline SmartPtr(T* pointer, bool bAddRef = true) : pointer_(pointer), base_(pointer) |
---|
[5804] | 146 | { |
---|
[5805] | 147 | if (this->base_ && bAddRef) |
---|
| 148 | this->base_->incrementReferenceCount(); |
---|
[5804] | 149 | } |
---|
| 150 | |
---|
[7401] | 151 | /// Copy-constructor |
---|
[5805] | 152 | inline SmartPtr(const SmartPtr& other) : pointer_(other.pointer_), base_(other.base_) |
---|
| 153 | { |
---|
| 154 | if (this->base_) |
---|
| 155 | this->base_->incrementReferenceCount(); |
---|
| 156 | } |
---|
| 157 | |
---|
[7401] | 158 | /// Copy-constructor for smart pointers to objects of another class. |
---|
[5804] | 159 | template <class O> |
---|
[5805] | 160 | inline SmartPtr(const SmartPtr<O>& other) : pointer_(other.get()), base_(other.base_) |
---|
[5804] | 161 | { |
---|
[5805] | 162 | if (this->base_) |
---|
| 163 | this->base_->incrementReferenceCount(); |
---|
[5804] | 164 | } |
---|
| 165 | |
---|
[7401] | 166 | /// Constructor: Initializes the smart pointer with the pointer that is stored in a WeakPtr. |
---|
[5823] | 167 | template <class O> |
---|
| 168 | inline SmartPtr(const WeakPtr<O>& other) : pointer_(other.get()), base_(other.getBase()) |
---|
| 169 | { |
---|
| 170 | if (this->base_) |
---|
| 171 | this->base_->incrementReferenceCount(); |
---|
| 172 | } |
---|
| 173 | |
---|
[7401] | 174 | /// Destructor: Decrements the reference counter. |
---|
[5804] | 175 | inline ~SmartPtr() |
---|
| 176 | { |
---|
[5805] | 177 | if (this->base_) |
---|
| 178 | this->base_->decrementReferenceCount(); |
---|
[5804] | 179 | } |
---|
[6417] | 180 | |
---|
[7401] | 181 | /// Assigns a new pointer. |
---|
[7268] | 182 | inline SmartPtr& operator=(T* pointer) |
---|
[5804] | 183 | { |
---|
| 184 | SmartPtr(pointer).swap(*this); |
---|
| 185 | return *this; |
---|
| 186 | } |
---|
| 187 | |
---|
[7401] | 188 | /// Assigns the wrapped pointer of another SmartPtr. |
---|
[7268] | 189 | inline SmartPtr& operator=(const SmartPtr& other) |
---|
[5804] | 190 | { |
---|
| 191 | SmartPtr(other).swap(*this); |
---|
| 192 | return *this; |
---|
| 193 | } |
---|
| 194 | |
---|
[7401] | 195 | /// Assigns the wrapped pointer of a SmartPtr of another class |
---|
[5804] | 196 | template <class O> |
---|
[7268] | 197 | inline SmartPtr& operator=(const SmartPtr<O>& other) |
---|
[5804] | 198 | { |
---|
| 199 | SmartPtr(other).swap(*this); |
---|
| 200 | return *this; |
---|
| 201 | } |
---|
| 202 | |
---|
[7401] | 203 | /// Assigns the wrapped pointer of a WeakPtr. |
---|
[5823] | 204 | template <class O> |
---|
[7268] | 205 | inline SmartPtr& operator=(const WeakPtr<O>& other) |
---|
[5823] | 206 | { |
---|
| 207 | SmartPtr(other).swap(*this); |
---|
| 208 | return *this; |
---|
| 209 | } |
---|
| 210 | |
---|
[7401] | 211 | /// Returns the wrapped pointer as @c T* |
---|
[5804] | 212 | inline T* get() const |
---|
| 213 | { |
---|
| 214 | return this->pointer_; |
---|
| 215 | } |
---|
| 216 | |
---|
[9571] | 217 | /// Returns the wrapped pointer as @c Destroyable* |
---|
| 218 | inline Destroyable* getBase() const |
---|
[5823] | 219 | { |
---|
| 220 | return this->base_; |
---|
| 221 | } |
---|
| 222 | |
---|
[7401] | 223 | /// Implicitly converts the SmartPtr to a pointer of type @c T* |
---|
[5804] | 224 | inline operator T*() const |
---|
[5805] | 225 | { |
---|
[5804] | 226 | return this->pointer_; |
---|
| 227 | } |
---|
| 228 | |
---|
[7401] | 229 | /// Overloaded operator, returns a pointer to the stored object. |
---|
[5804] | 230 | inline T* operator->() const |
---|
| 231 | { |
---|
[5807] | 232 | assert(this->pointer_ != 0); |
---|
[5804] | 233 | return this->pointer_; |
---|
| 234 | } |
---|
| 235 | |
---|
[7401] | 236 | /// Overloaded operator, returns a reference to the stored object. |
---|
[5804] | 237 | inline T& operator*() const |
---|
| 238 | { |
---|
[5807] | 239 | assert(this->pointer_ != 0); |
---|
[5804] | 240 | return *this->pointer_; |
---|
| 241 | } |
---|
| 242 | |
---|
[7401] | 243 | /// Returns true if the wrapped pointer is NULL. |
---|
[5804] | 244 | inline bool operator!() const |
---|
| 245 | { |
---|
| 246 | return (this->pointer_ == 0); |
---|
| 247 | } |
---|
| 248 | |
---|
[7401] | 249 | /// Swaps the contents of two smart pointers. |
---|
[5804] | 250 | inline void swap(SmartPtr& other) |
---|
| 251 | { |
---|
[5805] | 252 | { |
---|
| 253 | T* temp = this->pointer_; |
---|
| 254 | this->pointer_ = other.pointer_; |
---|
| 255 | other.pointer_ = temp; |
---|
| 256 | } |
---|
| 257 | { |
---|
[9571] | 258 | Destroyable* temp = this->base_; |
---|
[5805] | 259 | this->base_ = other.base_; |
---|
| 260 | other.base_ = temp; |
---|
| 261 | } |
---|
[5804] | 262 | } |
---|
| 263 | |
---|
[7401] | 264 | /// Resets the smart pointer (equivalent to assigning a NULL pointer). |
---|
[5804] | 265 | inline void reset() |
---|
| 266 | { |
---|
| 267 | SmartPtr().swap(*this); |
---|
| 268 | } |
---|
| 269 | |
---|
| 270 | private: |
---|
[7401] | 271 | T* pointer_; ///< The wrapped pointer to an object of type @a T |
---|
[9571] | 272 | Destroyable* base_; ///< The wrapped pointer, casted up to Destroyable (this is needed because with just a T* pointer, SmartPtr couln't be used with forward declarations) |
---|
[5804] | 273 | }; |
---|
| 274 | |
---|
[7401] | 275 | /// Swaps the contents of two smart pointers. |
---|
[5804] | 276 | template <class T> |
---|
| 277 | void swap(SmartPtr<T>& a, SmartPtr<T>& b) |
---|
| 278 | { |
---|
| 279 | a.swap(b); |
---|
| 280 | } |
---|
| 281 | |
---|
[7401] | 282 | /// Uses a static_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new SmartPtr<T>. |
---|
[5804] | 283 | template <class T, class U> |
---|
| 284 | SmartPtr<T> static_pointer_cast(const SmartPtr<U>& p) |
---|
| 285 | { |
---|
| 286 | return static_cast<T*>(p.get()); |
---|
| 287 | } |
---|
| 288 | |
---|
[7401] | 289 | /// Uses a const_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new SmartPtr<T>. |
---|
[5804] | 290 | template <class T, class U> |
---|
| 291 | SmartPtr<T> const_pointer_cast(const SmartPtr<U>& p) |
---|
| 292 | { |
---|
| 293 | return const_cast<T*>(p.get()); |
---|
| 294 | } |
---|
| 295 | |
---|
[7401] | 296 | /// Uses a dynamic_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new SmartPtr<T>. |
---|
[5804] | 297 | template <class T, class U> |
---|
| 298 | SmartPtr<T> dynamic_pointer_cast(const SmartPtr<U>& p) |
---|
| 299 | { |
---|
[7268] | 300 | return orxonox_cast<T*>(p.get()); |
---|
[5804] | 301 | } |
---|
| 302 | } |
---|
| 303 | |
---|
| 304 | #endif /* _SmartPtr_H__ */ |
---|