Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/trunk/src/libraries/core/SmartPtr.h @ 8470

Last change on this file since 8470 was 7401, checked in by landauf, 14 years ago

merged doc branch back to trunk

  • Property svn:eol-style set to native
File size: 11.8 KB
RevLine 
[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
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.
116*/
117
[5804]118#ifndef _SmartPtr_H__
119#define _SmartPtr_H__
120
121#include "CorePrereqs.h"
122
[5807]123#include <cassert>
[5823]124
[7268]125#include "Identifier.h"
[5807]126#include "OrxonoxClass.h"
[5823]127#include "WeakPtr.h"
[5804]128
129namespace orxonox
130{
[7401]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    */
[5804]136    template <class T>
137    class SmartPtr
138    {
139        public:
[7401]140            /// Constructor: Initializes the smart pointer with a null pointer.
[5805]141            inline SmartPtr() : pointer_(0), base_(0)
[5804]142            {
143            }
144
[7401]145            /// Constructor: Used to explicitly initialize the smart pointer with a null pointer
[5805]146            inline SmartPtr(int) : pointer_(0), base_(0)
[5804]147            {
148            }
149
[7401]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)
[5805]151            inline SmartPtr(T* pointer, bool bAddRef = true) : pointer_(pointer), base_(pointer)
[5804]152            {
[5805]153                if (this->base_ && bAddRef)
154                    this->base_->incrementReferenceCount();
[5804]155            }
156
[7401]157            /// Copy-constructor
[5805]158            inline SmartPtr(const SmartPtr& other) : pointer_(other.pointer_), base_(other.base_)
159            {
160                if (this->base_)
161                    this->base_->incrementReferenceCount();
162            }
163
[7401]164            /// Copy-constructor for smart pointers to objects of another class.
[5804]165            template <class O>
[5805]166            inline SmartPtr(const SmartPtr<O>& other) : pointer_(other.get()), base_(other.base_)
[5804]167            {
[5805]168                if (this->base_)
169                    this->base_->incrementReferenceCount();
[5804]170            }
171
[7401]172            /// Constructor: Initializes the smart pointer with the pointer that is stored in a WeakPtr.
[5823]173            template <class O>
174            inline SmartPtr(const WeakPtr<O>& other) : pointer_(other.get()), base_(other.getBase())
175            {
176                if (this->base_)
177                    this->base_->incrementReferenceCount();
178            }
179
[7401]180            /// Destructor: Decrements the reference counter.
[5804]181            inline ~SmartPtr()
182            {
[5805]183                if (this->base_)
184                    this->base_->decrementReferenceCount();
[5804]185            }
[6417]186
[7401]187            /// Used to assign a null pointer.
[7268]188            inline SmartPtr& operator=(int)
[5805]189            {
190                SmartPtr(0).swap(*this);
191                return *this;
192            }
[5804]193
[7401]194            /// Assigns a new pointer.
[7268]195            inline SmartPtr& operator=(T* pointer)
[5804]196            {
197                SmartPtr(pointer).swap(*this);
198                return *this;
199            }
200
[7401]201            /// Assigns the wrapped pointer of another SmartPtr.
[7268]202            inline SmartPtr& operator=(const SmartPtr& other)
[5804]203            {
204                SmartPtr(other).swap(*this);
205                return *this;
206            }
207
[7401]208            /// Assigns the wrapped pointer of a SmartPtr of another class
[5804]209            template <class O>
[7268]210            inline SmartPtr& operator=(const SmartPtr<O>& other)
[5804]211            {
212                SmartPtr(other).swap(*this);
213                return *this;
214            }
215
[7401]216            /// Assigns the wrapped pointer of a WeakPtr.
[5823]217            template <class O>
[7268]218            inline SmartPtr& operator=(const WeakPtr<O>& other)
[5823]219            {
220                SmartPtr(other).swap(*this);
221                return *this;
222            }
223
[7401]224            /// Returns the wrapped pointer as @c T*
[5804]225            inline T* get() const
226            {
227                return this->pointer_;
228            }
229
[7401]230            /// Returns the wrapped pointer as @c OrxonoxClass*
[5823]231            inline OrxonoxClass* getBase() const
232            {
233                return this->base_;
234            }
235
[7401]236            /// Implicitly converts the SmartPtr to a pointer of type @c T*
[5804]237            inline operator T*() const
[5805]238            {
[5804]239                return this->pointer_;
240            }
241
[7401]242            /// Overloaded operator, returns a pointer to the stored object.
[5804]243            inline T* operator->() const
244            {
[5807]245                assert(this->pointer_ != 0);
[5804]246                return this->pointer_;
247            }
248
[7401]249            /// Overloaded operator, returns a reference to the stored object.
[5804]250            inline T& operator*() const
251            {
[5807]252                assert(this->pointer_ != 0);
[5804]253                return *this->pointer_;
254            }
255
[7401]256            /// Returns true if the wrapped pointer is NULL.
[5804]257            inline bool operator!() const
258            {
259                return (this->pointer_ == 0);
260            }
261
[7401]262            /// Swaps the contents of two smart pointers.
[5804]263            inline void swap(SmartPtr& other)
264            {
[5805]265                {
266                    T* temp = this->pointer_;
267                    this->pointer_ = other.pointer_;
268                    other.pointer_ = temp;
269                }
270                {
271                    OrxonoxClass* temp = this->base_;
272                    this->base_ = other.base_;
273                    other.base_ = temp;
274                }
[5804]275            }
276
[7401]277            /// Resets the smart pointer (equivalent to assigning a NULL pointer).
[5804]278            inline void reset()
279            {
280                SmartPtr().swap(*this);
281            }
282
283        private:
[7401]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)
[5804]286    };
287
[7401]288    /// Swaps the contents of two smart pointers.
[5804]289    template <class T>
290    void swap(SmartPtr<T>& a, SmartPtr<T>& b)
291    {
292        a.swap(b);
293    }
294
[7401]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>.
[5804]296    template <class T, class U>
297    SmartPtr<T> static_pointer_cast(const SmartPtr<U>& p)
298    {
299        return static_cast<T*>(p.get());
300    }
301
[7401]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>.
[5804]303    template <class T, class U>
304    SmartPtr<T> const_pointer_cast(const SmartPtr<U>& p)
305    {
306        return const_cast<T*>(p.get());
307    }
308
[7401]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>.
[5804]310    template <class T, class U>
311    SmartPtr<T> dynamic_pointer_cast(const SmartPtr<U>& p)
312    {
[7268]313        return orxonox_cast<T*>(p.get());
[5804]314    }
315}
316
317#endif /* _SmartPtr_H__ */
Note: See TracBrowser for help on using the repository browser.