GrAL::ref_ptr< T > Class Template Reference
[Memory management and smart pointers]

class for maintaining a assignable reference to another (often const) object More...

#include </home/guntram/tmp/GrAL/utilities/include/Utility/ref-ptr.h>

Inheritance diagram for GrAL::ref_ptr< T >:

[legend]

List of all members.

Public Member Functions
	ref_ptr (T &t)
	Store a reference to t.
	ref_ptr (T *tptr)
	Store a reference to *tptr.
template<class U >
	ref_ptr (U *uptr)
	ref_ptr (T *tptr, ownership own)
	Store either a reference or a shared pointer to *tptr.
template<class U >
	ref_ptr (U *uptr, ownership own)
	ref_ptr (ref_ptr< T > const &rhs)
ref_ptr< T > &	operator= (ref_ptr< T > const &rhs)
template<class U >
	ref_ptr (ref_ptr< U > const &rhs)
	conversion constructors
template<class U >
ref_ptr< T > &	operator= (ref_ptr< U > const &rhs)
	conversion assignment
template<class U >
void	swap (ref_ptr< U > const &rhs)
template<class U >
void	make_shared (U *uptr)
	Set to a shared pointer to uptr.
template<class U >
void	make_ref (U *uptr)
	Set to a reference to uptr.
void	make_copy ()
	make a copy of the pointee
bool	valid () const
void	clear ()
bool	is_shared () const
bool	is_reference () const
T *	get () const
T *	operator-> () const
T &	operator* () const
boost::shared_ptr< T > const &	get_ptr () const
Friends
bool	operator== (self const &c, T *p)
bool	operator== (T *p, self const &c)
bool	operator!= (self const &c, T *p)
bool	operator!= (T *p, self const &c)
Related Functions
(Note that these are not member functions.)
template<class T >
ref_ptr< T >	copy_to_ref_ptr (T const &t)
	Copy t to a ref_ptr.
template<class T >
ref_ptr< const T >	copy_to_const_ref_ptr (T const &t)
	Copy t to a const ref_ptr.
template<class T >
ref_ptr< T >	ref_to_ref_ptr (T &t)
	Reference t in a ref_ptr (no ownership transfer).
template<class T >
ref_ptr< const T >	const_ref_to_ref_ptr (T const &t)
	Reference t in a ref_ptr (no ownership transfer).

---

Detailed Description

template<class T>
class GrAL::ref_ptr< T >

class for maintaining a assignable reference to another (often const) object

Author:

Guntram Berti

The purpose of this class is to maintain a reference (pointer) to an object which may by allocated statically or dynamically. The motivating observation is the following: When referencing another object (say b of class B) with a member of an object a of class A, the allocation policy and life time of b may fall into different cases:

1. b is statically allocated, but its lifetime is at least as long than that of a:

         Grid g;
         VertexIterator v(g); // a <-> v, and b <-> g
   

2. b is statically allocated on the fly, i.e. a temporary, for example a light-weight object returned by a function:

          Vertex v(* g.FirstVertex());
          boundary_type bd(star(v));  // a <-> bd, and b <-> result of star(v)
          cout << bd.NumOfVertices(); // Danger, must not take just take address of temporary result star(v)
   

   (Note: star(v) is the set of elements incident to a vertex v. This is most likely to be calculated on-the-fly.)
3. b is dynamically allocated and manually managed, but the pointer to it has life time at least as long than that of a:

          Grid * g = new Grid(nv,nc);
          // ...
          VertexIterator v(g); // a <-> v, and b <-> g
   

4. b is dynamically allocated and managed by a smart pointer with sharing semantics:

         Grid g;
         subrange cells_to_remove(g); 
         // ...
         view2_type v2(cut_cells(g,cells_to_remove)); // a <-> v2, and b <-> result of cut_cells
   

   Here, cut_cells() is likely to return a dynamically allocated object, because it may be large. Of course, in this case, a smart pointer is the method of choice.

Items 1 and 3 are essentially the same, these can be handled by just storing the address of b, and there is no need to worry on life time of b in a.
Item 2 is different because the lifetime of is to short. In this case we have to create a permanent copy. However, when a longer lifetime of b is not needed, we do not want to incur the overhead of a dynamic allocation.
Item 4 means that we can simply copy the shared smart pointer.

The challenge is now to put everything under the hood of a unique pointer-like interface, and to use the constructor to differentiate between the cases (which does not work automatically).

In case 1 and 3, we just pass a plain reference or pointer to the object to the constructor of ref_ptr<>.
For filtering out case 2, we rely on the temporary object being wrappend into the temporary<> template.
For handling case 4, we also pass in a pointer, but must explicitely enable shared ownership.

Definition at line 193 of file ref-ptr.h.

---

Constructor & Destructor Documentation

template<class T>

GrAL::ref_ptr< T >::ref_ptr

(

T &

t

)

[inline, explicit]

Store a reference to t.

Postcondition:

is_reference()

Definition at line 208 of file ref-ptr.h.

template<class T>

GrAL::ref_ptr< T >::ref_ptr

(

T *

tptr

)

[inline, explicit]

Store a reference to *tptr.

If tptr points to dynamically allocated memory, deallocation remains in the responsibility of the caller.

Postcondition:

is_reference()

Definition at line 221 of file ref-ptr.h.

template<class T>

GrAL::ref_ptr< T >::ref_ptr	(	T *	tptr,
		ownership	own
	)			[inline]

Store either a reference or a shared pointer to *tptr.

Precondition:

if own == shared then tptr must point to dynamically allocated memory, i.e. calling delete tptr must be legal.

Postcondition:

if own == referenced then is_referenced() == true
if own == shared then is_shared() == true

Definition at line 241 of file ref-ptr.h.

---

Member Function Documentation

template<class T>

template<class U >

void GrAL::ref_ptr< T >::make_shared

(

U *

uptr

)

[inline]

Set to a shared pointer to uptr.

Precondition:

tuptr must point to dynamically allocated memory, i.e. calling delete uptr must be legal.

Postcondition:

is_shared()

Definition at line 341 of file ref-ptr.h.

template<class T>

void GrAL::ref_ptr< T >::make_copy

(

)

[inline]

make a copy of the pointee

Precondition:

valid()

Postcondition:

valid() && shared()

Definition at line 361 of file ref-ptr.h.

---

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

• Utility/ref-ptr.h