rutz::shared_ptr< T > Class Template Reference

A thread-safe smart pointer with reference counted copy semantics. More...

#include <rutz/shared_ptr.h>

Inheritance diagram for rutz::shared_ptr< T >:

Inheritance graph
[legend]
Collaboration diagram for rutz::shared_ptr< T >:

Collaboration graph
[legend]

List of all members.

Public Member Functions

 shared_ptr (T *p=0)
 Construct from a raw pointer. WARNING: do this only ONCE per pointer!
 shared_ptr (const shared_ptr &r) throw ()
 Copy another shared_ptr. The ref count is incremented by one.
 ~shared_ptr ()
 Destructor decrements the ref count by one.
shared_ptroperator= (const shared_ptr &r)
 Assign from another shared_ptr. The ref count is incremented by one.
template<class TT>
 shared_ptr (const shared_ptr< TT > &r) throw ()
 Copy construct from a shared_ptr of a different type.
template<class TT>
shared_ptroperator= (const shared_ptr< TT > &r)
 Assign from a shared_ptr of a different type.
template<class TT>
shared_ptrdyn_cast_from (const shared_ptr< TT > &r)
 Assign from a shared_ptr of a different type, with dynamic casting.
template<class TT>
shared_ptrdynCastFrom (const shared_ptr< TT > &r)
void reset (T *p=0)
 Make the shared_ptr point to a different (optionally null) pointee.
T & operator* () const throw ()
 Get a reference to the pointee.
T * operator-> () const throw ()
 Get the pointee for accessing its members.
T * get () const throw ()
 Get the pointee.
bool is_valid () const throw ()
 Query whether the pointee is non-null.
bool is_invalid () const throw ()
 Query whether the pointee is non-null.
int use_count () const throw ()
 Query how many shared_ptr's are sharing the pointee.
bool unique () const throw ()
 Query whether the shared_ptr is the unique owner of its pointee.
void swap (shared_ptr< T > &that) throw ()
 Swap the pointees of two shared_ptr's.

Friends

class shared_ptr


Detailed Description

template<class T>
class rutz::shared_ptr< T >

A thread-safe smart pointer with reference counted copy semantics.

The object pointed to is deleted when the last shared_ptr pointing to it is destroyed or reset. Take note of the WARNING given in the documentation for the constructor that takes a raw pointer as its argument.

Borrowed and modified from boost.org smart_ptr.hpp Original copyright notice:

(C) Copyright Greg Colvin and Beman Dawes 1998, 1999. Permission to copy, use, modify, sell and distribute this software is granted provided this copyright notice appears in all copies. This software is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.

Definition at line 80 of file shared_ptr.h.


Constructor & Destructor Documentation

template<class T>
rutz::shared_ptr< T >::shared_ptr ( T *  p = 0  )  [inline, explicit]

Construct from a raw pointer. WARNING: do this only ONCE per pointer!

Bad Things (TM) will happen if this constructor is used multiple times to make multiple shared_ptr's from a single raw pointer; that's because each shared_ptr will start off thinking that it is the unique owner, and so they will each start their own ref count. If multiple shared_ptr's are needed for the same object (after all, that's the whole point of a shared ptr), only the first one should be constructed from the raw pointer, and subsequent ones should be constructed from the first using the copy constructor or assignment operator.

Definition at line 262 of file shared_ptr.h.

References rutz::mutex_atomic_int::atomic_set(), and rutz::full_object_cast().

template<class T>
rutz::shared_ptr< T >::~shared_ptr (  )  [inline]

Destructor decrements the ref count by one.

If we were the last pointer to the pointee, then the pointee and the reference count are both delete'd.

Definition at line 295 of file shared_ptr.h.

References rutz::mutex_atomic_int::atomic_decr_test_zero().

template<class T>
template<class TT>
rutz::shared_ptr< T >::shared_ptr ( const shared_ptr< TT > &  r  )  throw () [inline]

Copy construct from a shared_ptr of a different type.

The other type TT must be related to T by an appropriate inheritance relationship or by a change in const-qualification.

Definition at line 316 of file shared_ptr.h.

References rutz::mutex_atomic_int::atomic_incr().


Member Function Documentation

template<class T>
template<class TT>
rutz::shared_ptr< T > & rutz::shared_ptr< T >::operator= ( const shared_ptr< TT > &  r  )  [inline]

Assign from a shared_ptr of a different type.

The other type TT must be related to T by an appropriate inheritance relationship or by a change in const-qualification.

Definition at line 326 of file shared_ptr.h.

References rutz::shared_ptr< T >::swap().

template<class T>
template<class TT>
rutz::shared_ptr< T > & rutz::shared_ptr< T >::dyn_cast_from ( const shared_ptr< TT > &  r  )  [inline]

Assign from a shared_ptr of a different type, with dynamic casting.

This is the shared_ptr equivalent of doing a dynamic_cast between two raw pointers. Doing 'shared_ptr<T> ptr; ptr.dynCastFrom(other);' with 'other' a shared_ptr will internally do a dynamic_cast from TT* to T* and will assign the result to ptr. If the dynamic_cast succeeds, ptr and other will share the pointee as if they were two normal shared_ptr onto it (even though ptr and other are shared_ptr of different types). If the dynamic_cast fails then ptr will point to NULL. Typical usage of this is to recover an expected derived class from a base class: for example,

get our visual cortex from Brain. Brain provides a getVC()
function which returns a shared_ptr onto the VisualCortex
base class no matter which derivation of that we are actually
running right now:
      shared_ptr<VisualCortex> vcx = brain->getVC();

do something special if our VisualCortex actually happens to
be of type VisualCortexEyeMvt which is derived from
VisualCortex:
      shared_ptr<VisualCortexEyeMvt> vcem;
      vcem.dynCastFrom(vcx);

vcem points to NULL unless the pointee of vcx could be
dynamic_cast'ed to vcem's type.
      if (vcem.isValid()) {
yes, indeed we are running a VisualCortexEyeMvt
      ...
      }
      

Note: make sure you always use virtual destructors in your pointees, especially when you use dynCastFrom. Indeed, whichever shared_ptr is the last one to run out of scope will destroy the pointee.

Definition at line 336 of file shared_ptr.h.

References rutz::mutex_atomic_int::atomic_decr_test_zero(), rutz::mutex_atomic_int::atomic_incr(), rutz::mutex_atomic_int::atomic_set(), rutz::shared_ptr< T >::pn, and rutz::shared_ptr< T >::px.

Referenced by rutz::dyn_cast(), and rutz::dyn_cast_to_from().


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

The software described here is Copyright (c) 1998-2005, Rob Peters.
This page was generated Wed Dec 3 06:56:46 2008 by Doxygen version 1.5.5.