Changeset 7373 for code/branches/doc/src/libraries/core/SmartPtr.h
- Timestamp:
- Sep 7, 2010, 11:24:47 PM (14 years ago)
- File:
-
- 1 edited
-
code/branches/doc/src/libraries/core/SmartPtr.h (modified) (23 diffs)
Legend:
- Unmodified
- Added
- Removed
-
code/branches/doc/src/libraries/core/SmartPtr.h
r7363 r7373 37 37 @file 38 38 @ingroup Object SmartPtr 39 @brief Definition of SmartPtr<T>. 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 46 from orxonox::OrxonoxClass, because it's an intrusive implementation, meaning the 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 80 In this example we assume that OtherClass is a child of OrxonoxClass. We don't care 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. 39 116 */ 40 117 … … 52 129 namespace orxonox 53 130 { 131 /** 132 @brief A smart pointer which wraps a pointer to an object and keeps this object alive as long as the smart pointer exists. 133 134 @see See @ref SmartPtrExample "this description" for more information and an example. 135 */ 54 136 template <class T> 55 137 class SmartPtr 56 138 { 57 139 public: 140 /// Constructor: Initializes the smart pointer with a null pointer. 58 141 inline SmartPtr() : pointer_(0), base_(0) 59 142 { 60 143 } 61 144 145 /// Constructor: Used to explicitly initialize the smart pointer with a null pointer 62 146 inline SmartPtr(int) : pointer_(0), base_(0) 63 147 { 64 148 } 65 149 150 /// 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) 66 151 inline SmartPtr(T* pointer, bool bAddRef = true) : pointer_(pointer), base_(pointer) 67 152 { … … 70 155 } 71 156 157 /// Copy-constructor 72 158 inline SmartPtr(const SmartPtr& other) : pointer_(other.pointer_), base_(other.base_) 73 159 { … … 76 162 } 77 163 164 /// Copy-constructor for smart pointers to objects of another class. 78 165 template <class O> 79 166 inline SmartPtr(const SmartPtr<O>& other) : pointer_(other.get()), base_(other.base_) … … 83 170 } 84 171 172 /// Constructor: Initializes the smart pointer with the pointer that is stored in a WeakPtr. 85 173 template <class O> 86 174 inline SmartPtr(const WeakPtr<O>& other) : pointer_(other.get()), base_(other.getBase()) … … 90 178 } 91 179 180 /// Destructor: Decrements the reference counter. 92 181 inline ~SmartPtr() 93 182 { … … 96 185 } 97 186 187 /// Used to assign a null pointer. 98 188 inline SmartPtr& operator=(int) 99 189 { … … 102 192 } 103 193 194 /// Assigns a new pointer. 104 195 inline SmartPtr& operator=(T* pointer) 105 196 { … … 108 199 } 109 200 201 /// Assigns the wrapped pointer of another SmartPtr. 110 202 inline SmartPtr& operator=(const SmartPtr& other) 111 203 { … … 114 206 } 115 207 208 /// Assigns the wrapped pointer of a SmartPtr of another class 116 209 template <class O> 117 210 inline SmartPtr& operator=(const SmartPtr<O>& other) … … 121 214 } 122 215 216 /// Assigns the wrapped pointer of a WeakPtr. 123 217 template <class O> 124 218 inline SmartPtr& operator=(const WeakPtr<O>& other) … … 128 222 } 129 223 224 /// Returns the wrapped pointer as @c T* 130 225 inline T* get() const 131 226 { … … 133 228 } 134 229 230 /// Returns the wrapped pointer as @c OrxonoxClass* 135 231 inline OrxonoxClass* getBase() const 136 232 { … … 138 234 } 139 235 236 /// Implicitly converts the SmartPtr to a pointer of type @c T* 140 237 inline operator T*() const 141 238 { … … 143 240 } 144 241 242 /// Overloaded operator, returns a pointer to the stored object. 145 243 inline T* operator->() const 146 244 { … … 149 247 } 150 248 249 /// Overloaded operator, returns a reference to the stored object. 151 250 inline T& operator*() const 152 251 { … … 155 254 } 156 255 256 /// Returns true if the wrapped pointer is NULL. 157 257 inline bool operator!() const 158 258 { … … 160 260 } 161 261 262 /// Swaps the contents of two smart pointers. 162 263 inline void swap(SmartPtr& other) 163 264 { … … 174 275 } 175 276 277 /// Resets the smart pointer (equivalent to assigning a NULL pointer). 176 278 inline void reset() 177 279 { … … 180 282 181 283 private: 182 T* pointer_; 183 OrxonoxClass* base_; 284 T* pointer_; ///< The wrapped pointer to an object of type @a T 285 OrxonoxClass* base_; ///< The wrapped pointer, casted up to OrxonoxClass (this is needed because with just a T* pointer, SmartPtr couln't be used with forward declarations) 184 286 }; 185 287 288 /// Swaps the contents of two smart pointers. 186 289 template <class T> 187 290 void swap(SmartPtr<T>& a, SmartPtr<T>& b) … … 190 293 } 191 294 295 /// 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>. 192 296 template <class T, class U> 193 297 SmartPtr<T> static_pointer_cast(const SmartPtr<U>& p) … … 196 300 } 197 301 302 /// 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>. 198 303 template <class T, class U> 199 304 SmartPtr<T> const_pointer_cast(const SmartPtr<U>& p) … … 202 307 } 203 308 309 /// 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>. 204 310 template <class T, class U> 205 311 SmartPtr<T> dynamic_pointer_cast(const SmartPtr<U>& p)
Note: See TracChangeset
for help on using the changeset viewer.
