StrongPtr.h File Reference

Definition of StrongPtr<T>, wraps a pointer to an object and keeps it alive. More...

#include "core/CorePrereqs.h"
#include <cassert>
#include "core/object/Destroyable.h"
#include "WeakPtr.h"

Go to the source code of this file.

Classes
class	orxonox::StrongPtr< T >
	A strong pointer which wraps a pointer to an object and keeps this object alive as long as the strong pointer exists. More...

Namespaces
	orxonox
	Die Wagnis Klasse hat die folgenden Aufgaben:

Functions
template<class T , class U >
StrongPtr< T >	orxonox::const_pointer_cast (const StrongPtr< U > &p)
	Uses a const_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new StrongPtr<T>. More...
template<class T , class U >
StrongPtr< T >	orxonox::dynamic_pointer_cast (const StrongPtr< U > &p)
	Uses a dynamic_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new StrongPtr<T>. More...
template<class T , class U >
StrongPtr< T >	orxonox::static_pointer_cast (const StrongPtr< U > &p)
	Uses a static_cast to cast a pointer of type U* to a pointer of type T* and returns it in a new StrongPtr<T>. More...
template<class T >
void	orxonox::swap (StrongPtr< T > &a, StrongPtr< T > &b)
	Swaps the contents of two strong pointers. More...

Detailed Description

Definition of StrongPtr<T>, wraps a pointer to an object and keeps it alive.

orxonox::StrongPtr is an implementation of a smart pointer - it wraps a pointer to an object and keeps this object alive until no StrongPtr points to this object anymore. In contrast to std::shared_ptr, StrongPtr works only with classes that are derived from orxonox::Destroyable, because it's an intrusive implementation, meaning the reference counter is stored in the object itself.

It's possible to use normal pointers and strong pointers to an object simultaneously. You don't have to use StrongPtr all the time, you can create a StrongPtr for an object at any time and also convert it back to a normal pointer if you like. This is possible because the reference counter is stored in the object itself and not in StrongPtr (in contrast to std::shared_ptr).

Important: If you want to delete an object, you must not use delete object but rather object->destroy(). This function will check if there are strong pointers pointing to the object. If yes, the object will be kept alive until all strong pointers are destroyed. If no, the object is deleted instantly.

If all strong pointers that point to an object are destroyed, but you never called object->destroy() before, the object will not be deleted! All a StrongPtr will do is to really just keep an object alive, but it will not delete it automatically unless you tried to destroy it before.

Example:

class MyClass                                           // class declaration
{
    public:
        void setObject(OtherClass* object)              // passes a normal pointer which will be stored in a StrongPtr
            { this->object_ = object; }

        OtherClass* getObject() const                   // converts the StrongPtr to a normal pointer and returns it
            { return this->object_; }

    private:
        StrongPtr<OtherClass> object_;                  // a pointer to an instance of OtherClass is stored in a StrongPtr
};

In this example we assume that OtherClass is a child of Destroyable. We don't care about the inheritance of MyClass though.

Now we create an instance of MyClass and assign a pointer to an instance of OtherClass:

MyClass* myclass = new MyClass();                       // create an instance of MyClass
OtherClass* object = new OtherClass();                  // create an instance of OtherClass
myclass->setObject(object);                             // the object is now stored in a StrongPtr inside myclass

object->destroy();                                      // we try to destroy object, but there's still a StrongPtr pointing at it.

# object still exists at this point (because a StrongPtr points at it)

delete myclass;                                         // now we delete myclass, which also destroys the StrongPtr

# object doesn't exist anymore (because the StrongPtr is now destroyed)

Now we look at the same example, but we first delete myclass, then destroy object:

MyClass* myclass = new MyClass();                       // create an instance of MyClass
OtherClass* object = new OtherClass();                  // create an instance of OtherClass
myclass->setObject(object);                             // the object is now stored in a StrongPtr inside myclass

delete myclass;                                         // we delete myclass, which also destroys the StrongPtr

# object still exists at this point (because destroy() was not called yet)

object->destroy();                                      // now we try to destroy object, which works instantly

# object doesn't exist anymore (because we just destroyed it)

Note that in any case object->destroy() has to be called to delete the object. However if a StrongPtr points at it, the destruction is delayed until all StrongPtr are destroyed.