Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 11, 2010, 12:34:00 AM (14 years ago)
Author:
landauf
Message:

merged doc branch back to trunk

Location:
code/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • code/trunk

  • code/trunk/src/libraries/core/SmartPtr.h

    r7268 r7401  
    2929// Inspired by boost::intrusive_ptr by Peter Dimov
    3030
     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
    31118#ifndef _SmartPtr_H__
    32119#define _SmartPtr_H__
    … …  
    42129namespace orxonox
    43130{
     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    */
    44136    template <class T>
    45137    class SmartPtr
    46138    {
    47139        public:
     140            /// Constructor: Initializes the smart pointer with a null pointer.
    48141            inline SmartPtr() : pointer_(0), base_(0)
    49142            {
    50143            }
    51144
     145            /// Constructor: Used to explicitly initialize the smart pointer with a null pointer
    52146            inline SmartPtr(int) : pointer_(0), base_(0)
    53147            {
    54148            }
    55149
     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)
    56151            inline SmartPtr(T* pointer, bool bAddRef = true) : pointer_(pointer), base_(pointer)
    57152            {
    … …  
    60155            }
    61156
     157            /// Copy-constructor
    62158            inline SmartPtr(const SmartPtr& other) : pointer_(other.pointer_), base_(other.base_)
    63159            {
    … …  
    66162            }
    67163
     164            /// Copy-constructor for smart pointers to objects of another class.
    68165            template <class O>
    69166            inline SmartPtr(const SmartPtr<O>& other) : pointer_(other.get()), base_(other.base_)
    … …  
    73170            }
    74171
     172            /// Constructor: Initializes the smart pointer with the pointer that is stored in a WeakPtr.
    75173            template <class O>
    76174            inline SmartPtr(const WeakPtr<O>& other) : pointer_(other.get()), base_(other.getBase())
    … …  
    80178            }
    81179
     180            /// Destructor: Decrements the reference counter.
    82181            inline ~SmartPtr()
    83182            {
    … …  
    86185            }
    87186
     187            /// Used to assign a null pointer.
    88188            inline SmartPtr& operator=(int)
    89189            {
    … …  
    92192            }
    93193
     194            /// Assigns a new pointer.
    94195            inline SmartPtr& operator=(T* pointer)
    95196            {
    … …  
    98199            }
    99200
     201            /// Assigns the wrapped pointer of another SmartPtr.
    100202            inline SmartPtr& operator=(const SmartPtr& other)
    101203            {
    … …  
    104206            }
    105207
     208            /// Assigns the wrapped pointer of a SmartPtr of another class
    106209            template <class O>
    107210            inline SmartPtr& operator=(const SmartPtr<O>& other)
    … …  
    111214            }
    112215
     216            /// Assigns the wrapped pointer of a WeakPtr.
    113217            template <class O>
    114218            inline SmartPtr& operator=(const WeakPtr<O>& other)
    … …  
    118222            }
    119223
     224            /// Returns the wrapped pointer as @c T*
    120225            inline T* get() const
    121226            {
    … …  
    123228            }
    124229
     230            /// Returns the wrapped pointer as @c OrxonoxClass*
    125231            inline OrxonoxClass* getBase() const
    126232            {
    … …  
    128234            }
    129235
     236            /// Implicitly converts the SmartPtr to a pointer of type @c T*
    130237            inline operator T*() const
    131238            {
    … …  
    133240            }
    134241
     242            /// Overloaded operator, returns a pointer to the stored object.
    135243            inline T* operator->() const
    136244            {
    … …  
    139247            }
    140248
     249            /// Overloaded operator, returns a reference to the stored object.
    141250            inline T& operator*() const
    142251            {
    … …  
    145254            }
    146255
     256            /// Returns true if the wrapped pointer is NULL.
    147257            inline bool operator!() const
    148258            {
    … …  
    150260            }
    151261
     262            /// Swaps the contents of two smart pointers.
    152263            inline void swap(SmartPtr& other)
    153264            {
    … …  
    164275            }
    165276
     277            /// Resets the smart pointer (equivalent to assigning a NULL pointer).
    166278            inline void reset()
    167279            {
    … …  
    170282
    171283        private:
    172             T* pointer_;
    173             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)
    174286    };
    175287
     288    /// Swaps the contents of two smart pointers.
    176289    template <class T>
    177290    void swap(SmartPtr<T>& a, SmartPtr<T>& b)
    … …  
    180293    }
    181294
     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>.
    182296    template <class T, class U>
    183297    SmartPtr<T> static_pointer_cast(const SmartPtr<U>& p)
    … …  
    186300    }
    187301
     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>.
    188303    template <class T, class U>
    189304    SmartPtr<T> const_pointer_cast(const SmartPtr<U>& p)
    … …  
    192307    }
    193308
     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>.
    194310    template <class T, class U>
    195311    SmartPtr<T> dynamic_pointer_cast(const SmartPtr<U>& p)
Note: See TracChangeset for help on using the changeset viewer.