gutz::SmartPtr< T > Class Template Reference

#include <smartptr.h>

Inheritance diagram for gutz::SmartPtr< T >:

List of all members.

Detailed Description

template<class T>
class gutz::SmartPtr< T >

Smart Pointer class.

Smart Pointers are FUN FUN FUN.

For all intents an purposes, SmartPtrs work just like regular pointers, for instance you can:

      gutz::SmartPtr<MyClass> mcsp(); // create a "0" (Null) pointer by default
      mcsp = new MyClass();           // assign a pointer
      if( mcsp )                      // check if the pointer is non-zero
      if( !mcsp )                     // check if the pointer is zero
      if( mcsp == mcp )               // compare against another SmartPtr or raw pointer
      mcsp->myFunction();             // call a member function
      (*mcsp) = blah;                 // de-refrence
   
      // declaration of some function taking a pointer to MyClass
      void someFunc(MyClass *mcp);
      // call that function, but let the SmartPtr auto-cast to a pointer
      someFunc( mcsp ); // works fine too

The difference is that you don't need to call delete on your pointer, the SmartPtr<> will delete it when it gets deleted AND holds the last reference to that object. Just imagine a world with no memory leaks.

Const SmartPtrs work just like const ptrs.

 const SmartPtr<T> ~= T const*

You can always get at the "raw" pointer using:

 mySP.getPtr();

;

There is one major caveaut: Any class that can have a SmartPtr to it MUST be a subclass of gutz::Counted. This insures that we only have one (1) reference counter to any pointer, since it is a member of the class rather than a "proxy-class". One day I will implement an "AutoDeletPtr" which allows you to do the same thing with non-Counted classes. Forcing a Counted subclass, however, has advantages:

You can cast to different levels of the hierarchy and still have valid SmartPtrs
You can convert a pointer to a SmartPtr any time and still have valid refcounts
A Counted Base class insures, via type checking, that we have only 1 refcounter per ptr

SmartPtr is itself a subclass of counted so that you can have SmartPtrs to SmartPtrs and SmartPtrRef s.

Notes: Having issues? You shouldn't create a Counted object on the stack. If you do, and somebody else gets a smart pointer to that object, the smartptr will call delete on stack memory when the refcount drops to 0, which it might if the function doesn't delete the object first, both cases are bad. Here is an example that would cause an error.

     SmartPtr<T> newObjSP;
     T newObj;
     newObjSP = &newObj;

Notice that newObj is a local (stack) object. The right way:

     SmartPtr<T> newObjSP = new T;

the new object will get deleted when no one else has a reference to it.

Another caveaut of smartptrs is that if an object is using a smartptr to itself (why? who knows?), when the smartptr is deleted it might just delete the object that is using it. This happens especially when the constructor uses the smartptr, badness! If you have to do this, you need to increment your own reference counter first, then decrement when the ptr is gone (to avoid memory leaks). Again, be carefull, if the smartptr is created on the stack, you're pretty much screwed, because you can't possibly decrement after the smartptr is deleted. This reference to self situation can come up when iterators use smartptrs to the object they are iterating through. If the iterator is used internally, then when it goes away, the object itself might get deleted. Like say, when you need to iterate through yourself in the constructor :) You know you are getting into the danger zone when you do this (no pun intended):

     // somewhere in a member function of "MyObj"
     SmartPtr<MyObj> s(this);  /// this!!!

The right way would be:

     // somewhere in a member function of "MyObj"
     _incCount();
     SmartPtr<MyObj> *sp = new SmartPtr<MyObj>(this);
      <... do what you gota do ...>
     delete sp;
     _decCount();

Function calls are often the culprit, but this case is simpler, just inc and dec around the call:

     // somewhere in a member function of "MyObj"
     _incCount();
     someFunctionUsingSPs(SmartPtr<MyObj>(this));
     _decCount();

Remember, this only applies to use of a smartptr to "this" in the objects member functions, or any function call using the "this" pointer or a SmartPtr to "this" in the objects constructors.

Definition at line 180 of file smartptr.h.

get the contained pointer

T * getPtr ()

T *const getPtr () const

assign another smart pointer, or a raw pointer

SmartPtr & operator= (const SmartPtr &sp)

T * operator= (T *const ptr)

access members of T

ex
mySmartPtr->myFunction()

T * operator-> ()

T *const operator-> () const

De-reference like a regular pointer

ex
(*mySmartPtr).myFunction()

T & operator * ()

T & operator * () const

Implicit conversion to T*

good for function calls that take a regular pointer, for example:
///declaration of some function, taking a pointer void someFunc(someType *sc); ///calling "someFunc" using a smartptr as the parameter someFunc( mySP2someType ); /// converts SP to a raw pointer implicitly
also needed for "if" tests:
if( mySP2someType ) /// test if ptr != 0

operator T *const () const

Casting for convenience

Handles dynamic cast for you.

template<class CT> SmartPtr< CT > cast () const

mySubClassSP = myBaseClassSP.down_cast<MySubClassType>();
You don't need this for an "up-cast" since this thing automatically casts itself to a pointer which will then be up-casted by the compiler.

utilities, comparison ops

just like raw ptrs,
if(SP != 0)... if(SP == NULL)

bool operator! () const

bool isNull () const

just for convienence.

Public Types

typedef T type

Public Member Functions

SmartPtr ()

SmartPtr (T *const ptr)

SmartPtr (const SmartPtr &sp)

virtual ~SmartPtr ()

Protected Member Functions

void assign (T *const ref)

virtual void _incCount ()

gutz::Counted interface, increment reference count by one.

virtual void _decCount ()

gutz::Counted interface, decrement reference count by one.

virtual int _getCount () const

gutz::Counted interface, get the current reference count.

Protected Attributes

T * _ref

The only data we have is this pointer, so we have the same memory foot print of a regular pointer.

Friends

class SmartPtr

class SmartPtrRef

Member Typedef Documentation

template<class T>

typedef T gutz::SmartPtr< T >::type

Definition at line 183 of file smartptr.h.

Constructor & Destructor Documentation

template<class T>

gutz::SmartPtr< T >::SmartPtr ( ) [inline]

Definition at line 185 of file smartptr.h.

template<class T>

gutz::SmartPtr< T >::SmartPtr ( T *const ptr ) [inline]

Definition at line 186 of file smartptr.h.

template<class T>

gutz::SmartPtr< T >::SmartPtr ( const SmartPtr< T > & sp ) [inline]

Definition at line 187 of file smartptr.h.

template<class T>

virtual gutz::SmartPtr< T >::~SmartPtr ( ) [inline, virtual]

Definition at line 188 of file smartptr.h.

Member Function Documentation

virtual void gutz::Counted::_decCount ( ) [inline, protected, virtual, inherited]

gutz::Counted interface, decrement reference count by one.
Not generaly used by subclasses, mostly for collaboration with gutz::SmartPtr. Sometimes you need to call this though, see the documentation for gutz::SmartPtr
Definition at line 54 of file smartptr.h.
Referenced by TFImage::clear(), NrroImage::fBlendOverRGBA(), and Nrro::updateMinMax().

virtual int gutz::Counted::_getCount ( ) const [inline, protected, virtual, inherited]

gutz::Counted interface, get the current reference count.
Not generaly used by subclasses, mostly for collaboration with gutz::SmartPtr.
Definition at line 58 of file smartptr.h.

virtual void gutz::Counted::_incCount ( ) [inline, protected, virtual, inherited]

gutz::Counted interface, increment reference count by one.
Not generaly used by subclasses, mostly for collaboration with gutz::SmartPtr. Sometimes you need to call this though, see the documentation for gutz::SmartPtr
Definition at line 48 of file smartptr.h.
Referenced by TFImage::clear(), NrroImage::fBlendOverRGBA(), and Nrro::updateMinMax().

template<class T>

void gutz::SmartPtr< T >::assign ( T *const ref ) [inline, protected]

inc ref if non-zero
save off old reference
assign _ref = ref
delete the old reference
just a dec most of the time...
but if we hold the last reference, nuke it
Definition at line 285 of file smartptr.h.
Referenced by gutz::SmartPtr< TFElementList >::operator=(), gutz::SmartPtr< TFElementList >::SmartPtr(), and gutz::SmartPtr< TFElementList >::~SmartPtr().

template<class T>

template<class CT>

SmartPtr<CT> gutz::SmartPtr< T >::cast ( ) const [inline]

mySubClassSP = myBaseClassSP.down_cast<MySubClassType>();
You don't need this for an "up-cast" since this thing automatically casts itself to a pointer which will then be up-casted by the compiler.

Definition at line 249 of file smartptr.h.

template<class T>

T* const gutz::SmartPtr< T >::getPtr ( ) const [inline]

Definition at line 194 of file smartptr.h.

template<class T>

T* gutz::SmartPtr< T >::getPtr ( ) [inline]

Definition at line 193 of file smartptr.h.
Referenced by gutz::SmartPtr< TFElementList >::operator *(), gutz::SmartPtr< TFElementList >::operator T *const(), gutz::SmartPtr< TFElementList >::operator!(), gutz::SmartPtr< TFElementList >::operator->(), gutz::SmartPtr< TFElementList >::operator=(), and TFGL::TFGL().

template<class T>

bool gutz::SmartPtr< T >::isNull ( ) const [inline]

just for convienence.
access via,
mySp.isNull()

Definition at line 276 of file smartptr.h.
Referenced by TFItemVec::addItem(), Crank::checkKind(), and GrinderKeys::pconstID().

template<class T>

T& gutz::SmartPtr< T >::operator * ( ) const [inline]

Definition at line 218 of file smartptr.h.

template<class T>

T& gutz::SmartPtr< T >::operator * ( ) [inline]

Definition at line 217 of file smartptr.h.

template<class T>

gutz::SmartPtr< T >::operator T *const ( ) const [inline]

Definition at line 234 of file smartptr.h.

template<class T>

bool gutz::SmartPtr< T >::operator! ( ) const [inline]

Definition at line 261 of file smartptr.h.

template<class T>

T* const gutz::SmartPtr< T >::operator-> ( ) const [inline]

Definition at line 210 of file smartptr.h.

template<class T>

T* gutz::SmartPtr< T >::operator-> ( ) [inline]

Definition at line 209 of file smartptr.h.

template<class T>

T* gutz::SmartPtr< T >::operator= ( T *const ptr ) [inline]

Definition at line 202 of file smartptr.h.

template<class T>

SmartPtr& gutz::SmartPtr< T >::operator= ( const SmartPtr< T > & sp ) [inline]

Definition at line 200 of file smartptr.h.

Friends And Related Function Documentation

friend class SmartPtr [friend, inherited]

Definition at line 40 of file smartptr.h.
Referenced by Nrro::NrroIter< T >::NrroIter().

friend class SmartPtrRef [friend, inherited]

Definition at line 41 of file smartptr.h.

Member Data Documentation

template<class T>

T* gutz::SmartPtr< T >::_ref [protected]

The only data we have is this pointer, so we have the same memory foot print of a regular pointer.

Definition at line 283 of file smartptr.h.
Referenced by gutz::SmartPtr< TFElementList >::assign(), gutz::SmartPtr< TFElementList >::cast(), gutz::SmartPtr< TFElementList >::getPtr(), gutz::SmartPtr< TFElementList >::operator=(), and gutz::SmartPtr< TFElementList >::SmartPtr().

The documentation for this class was generated from the following file:

smartptr.h

Send questions, comments, and bug reports to:
jmk


get the contained pointer
T *	getPtr ()
T *const	getPtr () const
assign another smart pointer, or a raw pointer
SmartPtr &	operator= (const SmartPtr &sp)
T *	operator= (T *const ptr)
access members of T
ex mySmartPtr->myFunction()
T *	operator-> ()
T *const	operator-> () const
De-reference like a regular pointer
ex (*mySmartPtr).myFunction()
T &	operator * ()
T &	operator * () const
Implicit conversion to T*
good for function calls that take a regular pointer, for example: ///declaration of some function, taking a pointer void someFunc(someType *sc); ///calling "someFunc" using a smartptr as the parameter someFunc( mySP2someType ); /// converts SP to a raw pointer implicitly also needed for "if" tests: if( mySP2someType ) /// test if ptr != 0
	operator T *const () const
Casting for convenience
Handles dynamic cast for you.
template<class CT> SmartPtr< CT >	cast () const
	mySubClassSP = myBaseClassSP.down_cast<MySubClassType>(); You don't need this for an "up-cast" since this thing automatically casts itself to a pointer which will then be up-casted by the compiler.
utilities, comparison ops
just like raw ptrs, if(SP != 0)... if(SP == NULL)
bool	operator! () const
bool	isNull () const
	just for convienence.
Public Types
typedef T	type
Public Member Functions
	SmartPtr ()
	SmartPtr (T *const ptr)
	SmartPtr (const SmartPtr &sp)
virtual	~SmartPtr ()
Protected Member Functions
void	assign (T *const ref)
virtual void	_incCount ()
	gutz::Counted interface, increment reference count by one.
virtual void	_decCount ()
	gutz::Counted interface, decrement reference count by one.
virtual int	_getCount () const
	gutz::Counted interface, get the current reference count.
Protected Attributes
T *	_ref
	The only data we have is this pointer, so we have the same memory foot print of a regular pointer.
Friends
class	SmartPtr
class	SmartPtrRef

gutz::SmartPtr< T > Class Template Reference

Detailed Description

template<class T> class gutz::SmartPtr< T >

get the contained pointer

assign another smart pointer, or a raw pointer

access members of T

De-reference like a regular pointer

Implicit conversion to T*

Casting for convenience

utilities, comparison ops

Public Types

Public Member Functions

Protected Member Functions