code::SmartPtr< X > Class Template Reference

Inheritance diagram for code::SmartPtr< X >:

code::InitSmartPtr< X > code::InitSmartPtr< std::vector< code::code::Location > > code::InitSmartPtr< std::vector< code::code::Radial > > code::InitSmartPtr< std::vector< code::code::RadialSet > > code::InitSmartPtr< std::vector< code::code::SingleContourData > > code::InitSmartPtr< std::vector< code::Data2D< code::code::Angle, code::code::Angle, float > > > code::InitSmartPtr< std::vector< code::Data2D< code::code::Length, code::code::Length, float > > > List of all members.

Detailed Description

template<class X>
class code::SmartPtr< X >

SmartPtr does a templated reference counting mechanism.

The STL's auto_ptr ( in <memory> ) has destructive copy semantics. This means that if you copy two auto_ptr's and delete the second, the first one is left dangling. Such an auto_ptr has its uses but those uses don't include being able to store your objects in containers.

SmartPtr implements a different philosophy. In this case, a copy of a SmartPtr will increase the number of references to two. The object is deleted only when all references to it vanish.

Note that SmartPtr expects that the pointer you are handing it has been allocated with new; it won't work for arrays allocated with new[] or for objects that have been malloc'ed.

Hint: To "release" the object pointed to, assign to zero:

  SmartPtr< MyObject > myptr = new MyObject( ... );
  ...
  myptr = 0; // release !!
  
This will cause the object pointed to to be deleted if you have the only copy of it; if that object is being shared by many SmartPtr, you have done your part; the object will be deleted when every one else is done.
See also:
SmartPtr

InitSmartPtr

DerivedSmartPtr

InitDerivedSmartPtr

Author:
: Lakshman, NSSL
Version:
:
Id
code_SmartPtr.h,v 1.31 2009/06/02 20:17:40 lakshman Exp


Public Member Functions

 SmartPtr (X *p=0)
 Hand a pointer over to be reference-counted and maintained.
bool is_unique () const
 Is the pointed-to-object unique?
int copies () const
 Returns number of references to this SmartPtr.
bool is_ptr_valid () const
 Is the pointer that we are holding valid?
 SmartPtr (const SmartPtr< X > &orig)
 Copy constructor.
SmartPtr< const X > const_ptr () const
 Will return a reference-counted pointer to const X, so that functions that promise not to change the object can ask for, and receive, SmartPtr<const X>.
SmartPtroperator= (const SmartPtr< X > &orig)
bool operator< (const SmartPtr< X > &other) const
 To enable easy mapping of SmartPtrs of ordered objects to STL containers, the < operator is overloaded to compare the objects being pointed to.
bool operator== (const SmartPtr< X > &other) const
 To enable easy mapping of SmartPtrs of ordered objects to STL containers, the == operator is overloaded to compare the objects being pointed to.
bool is_stored_before (const SmartPtr< X > &other) const
 In some cases, it makes no sense for the objects themselves to be ordered; yet, you might want simply unique instances.
 ~SmartPtr ()
 Delete handed in pointer (using delete ) when the last SmartPtr that holds the pointer is destroyed.
X & operator * () const
 Use like a regular pointer; Asserts that the pointer is not null.
X * operator-> () const
 Use like a regular pointer; Asserts that the pointer is not null.
 SmartPtr (X *p, int *n)
 Copy constructor out of the internal data of an already existing ptr.
template<class D>
SmartPtr< D > recast ()
 Recast this SmartPtr to the desired type.
template<class D>
SmartPtr< const D > recast () const

Public Attributes

X * ptr
 Internal pointer storage.
int * numCopies
 Internal number of copies storage.


Constructor & Destructor Documentation

template<class X>
code::SmartPtr< X >::SmartPtr ( X *  p = 0  )  [inline]

Hand a pointer over to be reference-counted and maintained.

Note that SmartPtr expects that the pointer you are handing it has been allocated with "new". When the last copy of SmartPtr that points to this object is deleted, this object is also deleted. Make sure that no more than one SmartPtr handles a pointer.

template<class X>
code::SmartPtr< X >::SmartPtr ( const SmartPtr< X > &  orig  )  [inline]

Copy constructor.

Is not destructive; simply does reference counting.

template<class X>
code::SmartPtr< X >::~SmartPtr (  )  [inline]

Delete handed in pointer (using delete ) when the last SmartPtr that holds the pointer is destroyed.

template<class X>
code::SmartPtr< X >::SmartPtr ( X *  p,
int *  n 
) [inline]

Copy constructor out of the internal data of an already existing ptr.


Member Function Documentation

template<class X>
SmartPtr<const X> code::SmartPtr< X >::const_ptr (  )  const [inline]

Will return a reference-counted pointer to const X, so that functions that promise not to change the object can ask for, and receive, SmartPtr<const X>.

template<class X>
int code::SmartPtr< X >::copies (  )  const [inline]

Returns number of references to this SmartPtr.

template<class X>
bool code::SmartPtr< X >::is_ptr_valid (  )  const [inline]

Is the pointer that we are holding valid?

Note that this is a test only on whether the pointer is valid. There is no test of whether the object is valid; Usually objects that require initialization, etc. will have a isValid() member function. To prevent typographical errors, the name of this function is different. Just because the pointer is valid doesn't mean that the object is valid.

Use this function to check the return value from a function that promises to return a SmartPtr to something. The SmartPtr will hold an invalid pointer on error.

Returns:
true if pointer is valid (no error) and false if the pointer is invalid (error).

Reimplemented in code::InitSmartPtr< X >, code::InitSmartPtr< std::vector< code::SparseGrid3D::Pixel > >, code::InitSmartPtr< std::vector< char > >, code::InitSmartPtr< Impl >, code::InitSmartPtr< std::vector< code::SparseGrid2D::Pixel > >, code::InitSmartPtr< std::vector< float > >, code::InitSmartPtr< std::vector< D > >, code::InitSmartPtr< std::vector< code::code::RadialSet > >, code::InitSmartPtr< std::vector< code::code::Speed > >, code::InitSmartPtr< std::vector< X > >, code::InitSmartPtr< std::vector< code::Data3D< T2, T3, T4, X > > >, code::InitSmartPtr< BaseType >, code::InitSmartPtr< std::vector< code::code::SingleContourData > >, code::InitSmartPtr< std::vector< code::code::Location > >, code::InitSmartPtr< std::vector< code::code::Angle > >, code::InitSmartPtr< std::vector< code::Data2D< T3, T4, X > > >, code::InitSmartPtr< std::vector< code::Data2D< code::code::Angle, code::code::Angle, float > > >, code::InitSmartPtr< std::vector< code::code::Radial > >, and code::InitSmartPtr< std::vector< code::Data2D< code::code::Length, code::code::Length, float > > >.

template<class X>
bool code::SmartPtr< X >::is_stored_before ( const SmartPtr< X > &  other  )  const [inline]

In some cases, it makes no sense for the objects themselves to be ordered; yet, you might want simply unique instances.

In that case, pointers need to be compared using is_stored_before()

When the objects themselves are ordered, you should be using the < operator.

template<class X>
bool code::SmartPtr< X >::is_unique (  )  const [inline]

Is the pointed-to-object unique?

You can use this function to determine whether there is anybody else holding references to this object.

Returns:
true if the pointed-to-object is unique and false if there are one or more other modules/classes holding references to this object.

template<class X>
X& code::SmartPtr< X >::operator * (  )  const [inline]

Use like a regular pointer; Asserts that the pointer is not null.

Reimplemented in code::DerivedSmartPtr< BaseType, DerivedType >, code::InitDerivedSmartPtr< BaseType, DerivedType >, code::InitSmartPtr< X >, code::InitSmartPtr< std::vector< code::SparseGrid3D::Pixel > >, code::InitSmartPtr< std::vector< char > >, code::InitSmartPtr< Impl >, code::InitSmartPtr< std::vector< code::SparseGrid2D::Pixel > >, code::InitSmartPtr< std::vector< float > >, code::InitSmartPtr< std::vector< D > >, code::InitSmartPtr< std::vector< code::code::RadialSet > >, code::InitSmartPtr< std::vector< code::code::Speed > >, code::InitSmartPtr< std::vector< X > >, code::InitSmartPtr< std::vector< code::Data3D< T2, T3, T4, X > > >, code::InitSmartPtr< BaseType >, code::InitSmartPtr< std::vector< code::code::SingleContourData > >, code::InitSmartPtr< std::vector< code::code::Location > >, code::InitSmartPtr< std::vector< code::code::Angle > >, code::InitSmartPtr< std::vector< code::Data2D< T3, T4, X > > >, code::InitSmartPtr< std::vector< code::Data2D< code::code::Angle, code::code::Angle, float > > >, code::InitSmartPtr< std::vector< code::code::Radial > >, and code::InitSmartPtr< std::vector< code::Data2D< code::code::Length, code::code::Length, float > > >.

template<class X>
X* code::SmartPtr< X >::operator-> (  )  const [inline]

Use like a regular pointer; Asserts that the pointer is not null.

Reimplemented in code::DerivedSmartPtr< BaseType, DerivedType >, code::InitDerivedSmartPtr< BaseType, DerivedType >, code::InitSmartPtr< X >, code::InitSmartPtr< std::vector< code::SparseGrid3D::Pixel > >, code::InitSmartPtr< std::vector< char > >, code::InitSmartPtr< Impl >, code::InitSmartPtr< std::vector< code::SparseGrid2D::Pixel > >, code::InitSmartPtr< std::vector< float > >, code::InitSmartPtr< std::vector< D > >, code::InitSmartPtr< std::vector< code::code::RadialSet > >, code::InitSmartPtr< std::vector< code::code::Speed > >, code::InitSmartPtr< std::vector< X > >, code::InitSmartPtr< std::vector< code::Data3D< T2, T3, T4, X > > >, code::InitSmartPtr< BaseType >, code::InitSmartPtr< std::vector< code::code::SingleContourData > >, code::InitSmartPtr< std::vector< code::code::Location > >, code::InitSmartPtr< std::vector< code::code::Angle > >, code::InitSmartPtr< std::vector< code::Data2D< T3, T4, X > > >, code::InitSmartPtr< std::vector< code::Data2D< code::code::Angle, code::code::Angle, float > > >, code::InitSmartPtr< std::vector< code::code::Radial > >, and code::InitSmartPtr< std::vector< code::Data2D< code::code::Length, code::code::Length, float > > >.

template<class X>
bool code::SmartPtr< X >::operator< ( const SmartPtr< X > &  other  )  const [inline]

To enable easy mapping of SmartPtrs of ordered objects to STL containers, the < operator is overloaded to compare the objects being pointed to.

Hence, for this to be usable, the class X should have a < operator defined.

The behavior of the < and == operators is as follows:

  1. when neither pointer is valid, == would return true.
  2. when only one pointer is valid, the invalid pointer is always less than the valid pointer.
  3. when both pointers are valid, the objects pointed to are compared.

In some cases, it makes no sense for the objects themselves to be ordered; yet, you might want simply unique instances. In that case, pointers need to be compared. Use is_stored_before()

template<class X>
SmartPtr& code::SmartPtr< X >::operator= ( const SmartPtr< X > &  orig  )  [inline]

See also:
copy constructor.

template<class X>
bool code::SmartPtr< X >::operator== ( const SmartPtr< X > &  other  )  const [inline]

To enable easy mapping of SmartPtrs of ordered objects to STL containers, the == operator is overloaded to compare the objects being pointed to.

Hence, for this to be usable, the class X should have a == operator defined.

The behavior of the < and == operators is as follows:

  1. when neither pointer is valid, == would return true.
  2. when only one pointer is valid, the invalid pointer is always less than the valid pointer.
  3. when both pointers are valid, the objects pointed to are compared.

In some cases, it makes no sense for the objects themselves to be ordered; yet, you might want simply unique instances. In that case, pointers need to be compared. Use is_stored_before()

template<class X>
template<class D>
SmartPtr<const D> code::SmartPtr< X >::recast (  )  const [inline]

template<class X>
template<class D>
SmartPtr<D> code::SmartPtr< X >::recast (  )  [inline]

Recast this SmartPtr to the desired type.

An empty SmartPtr is returned if type conversion fails.

class A { ... }; class B: public A { ... }; class C: public B { ... }; class Unrelated { ... };

SmartPtr b = new C (); SmartPtr a = b.recast<A>(); // upcast SmartPtr<C> c = b.recast<C>(); // downcast assert (a.copies() == 3);

SmartPtr<Unrelated> u = b.recast<Unrelated>(); assert (!u.is_ptr_valid()); assert (a.copies() == 3);


Member Data Documentation

template<class X>
int* code::SmartPtr< X >::numCopies

Internal number of copies storage.

DerivedSmartPtr has access.

template<class X>
X* code::SmartPtr< X >::ptr

Internal pointer storage.

DerivedSmartPtr has access.


Generated on Fri May 4 13:40:13 2012 for WDSS-IIw2 by  doxygen 1.4.7