gum::RefPtr< Val > Class Template Reference

Smart pointersaGrUM's smart pointers keep track of the number of times the value they point to is referenced. More...

#include <agrum/core/refPtr.h>

Public Member Functions
template<typename DownVal >
INLINE	RefPtr (const RefPtr< DownVal > &from)
template<typename DownVal >
INLINE RefPtr< Val > &	operator= (const RefPtr< DownVal > &from)
Constructors / Destructors
	RefPtr (Val *val=0)
	Default constructor. More...
	RefPtr (const RefPtr< Val > &from)
	Copy constructor. More...
template<typename DownVal >
	RefPtr (const RefPtr< DownVal > &from)
	Copy constructor for downcastable pointers. More...
	~RefPtr ()
	Class destructor. More...
Accessors / Modifiers
	operator bool () const
	Checks whether a RefPtr points toward something. More...
void	clear ()
	Makes the smart pointer point to 0. More...
unsigned int	refCount () const
	Returns the number of smart pointer referencing the contained pointer. More...
Operators
RefPtr< Val > &	operator= (const RefPtr< Val > &from)
	Copy operator. More...
RefPtr< Val > &	operator= (Val *from)
	Copy operator. More...
template<typename DownVal >
RefPtr< Val > &	operator= (const RefPtr< DownVal > &from)
	Copy operator for downcastable pointers. More...
bool	operator== (const RefPtr< Val > &from) const
	Checks whether two RefPtr<Val> are smart pointers for the same element. More...
bool	operator!= (const RefPtr< Val > &from) const
	Checks whether two RefPtr<Val> are smart pointers for different elements. More...
Val *	operator-> () const
	Dereferencing operator. More...
Val &	operator* ()
	Dereferencing operator. More...
const Val &	operator* () const
	Const dereferencing operator. More...

Friends
void	swap (RefPtr< Val > &, RefPtr< Val > &)
	The swap function must access to gum::RefPtr private parts. More...

Internals
template<typename T >
class	RefPtr
	A friend to allow downcastings. More...
template<typename T >
class	HashFunc
	A friend for hashing quickly ref pointers. More...
Val *	__val
	The dumb pointer encapsulated into the "smart" pointer. More...
unsigned int *	__refcount
	A reference counter on *val. More...
void	__destroy (unsigned int *, Val *)
	A function to remove the content of the smart pointer, if any. More...
unsigned int *	__refCountPtr () const
	A function to return the refcount pointer. More...

Detailed Description

template<typename Val>
class gum::RefPtr< Val >

Smart pointers

aGrUM's smart pointers keep track of the number of times the value they point to is referenced.

When all smart pointers on a given value have been deleted, the value itself is also deleted. Thus, using RefPtr, you do not have to worry anymore about memory leaks. Note however that smart pointers impose some constraints on the way you program. Here are some rules of thumb: when several smart pointers must point to the same value, use only once the constructor taking in argument *val, and use the copy constructor or the assignment operator for the other smart pointers, else all the smart pointers will think they point to different values and thus they will all try to deallocate the dumb pointer they encapsulate, hence resulting in segmentation faults. In fact, the correct way to use the *val constructor is writing things like

RefPtr ( new myObject ) 

In particular, never deallocate yourself a dumb pointer you have encapsulated into a smart pointer.

Usage example:

// creation of smart pointer
RefPtr<int> ptr1 (new int (4));

// copying (and sharing) this pointer into new smart pointers
RefPtr<int> ptr2 = ptr1, ptr3;
ptr3 = ptr1;

// make ptr2 point toward nothing (this does not deallocate int (4) as it
// is pointed to by ptr1 and ptr3)
ptr2.clear ();

// modifying the value pointed to by the dumb pointer contained in ptr1
*ptr1 = 5;

// print the content of ptr3
cerr << *ptr3 << " = 5" << endl;

// check whether ptr1 and ptr3 reference the same dumb pointer
if (ptr1 == ptr2) cerr << "reference the same dumb pointer" << endl;

// check whether ptr1 and ptr2 contain a dumb pointer
if (ptr1 && !ptr2) cerr << "check containers" << endl;

Template Parameters

Val	The type referenced by the gum::RefPtr.

Definition at line 117 of file refPtr.h.

Constructor & Destructor Documentation

RefPtr() [1/4]

template<typename Val >

INLINE gum::RefPtr< Val >::RefPtr ( Val *  val = 0 )

explicit

Default constructor.

This constructor creates an object encapsulating the pointer passed in argument. No copy of the value pointed to by the pointer is performed. The RefPtr assumes that the value pointed to has been allocated on the heap using the new operator. If this is not the case, then using RefPtr will result in an undefined behavior when the RefPtr is destroyed (ok, we all know what it means: a segmentation fault). To avoid deleting several times the pointer encapsulated, the safe way to use the RefPtr is certainly through calls like:

RefPtr( new myObject ) 

Passing an already allocated pointer to the constructor is not forbidden. However, in this case, care should be taken not to allow external functions to delete the value pointed to by val. Moreover, care should be taken not to allow creating multiple RefPtr using this constructor on the same val. This would lead to unexpected results after deletion of the first RefPtr.

Parameters

val	The dumb pointer encapsulated into the object (make sure it is allocated on the heap)

Exceptions

std::bad_alloc

Raised if the complete RefPtr structure cannot be set properly.

Definition at line 36 of file refPtr_tpl.h.

                                     :
      __val(v), __refcount(v ? new unsigned int(1U) : 0) {
    // for debugging purposes
    GUM_CONSTRUCTOR(RefPtr);
  }

RefPtr() [2/4]

template<typename Val >

INLINE gum::RefPtr< Val >::RefPtr

(

const RefPtr< Val > &

from

)

Copy constructor.

Parameters

from	the smart pointer we wish to make a copy.

Definition at line 45 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__refcount.

                                                        :
      __val(from.__val), __refcount(from.__refcount) {
    // for debugging purposes
    GUM_CONS_CPY(RefPtr);

    if (__refcount) ++*__refcount;
  }

RefPtr() [3/4]

template<typename Val>

template<typename DownVal >

gum::RefPtr< Val >::RefPtr

(

const RefPtr< DownVal > &

from

)

Copy constructor for downcastable pointers.

Parameters

from	the smart pointer we wish to make a copy.

Template Parameters

DownVal

The downcastable type.

~RefPtr()

template<typename Val >

INLINE gum::RefPtr< Val >::~RefPtr

(

)

Class destructor.

Decrements the ref count and deletes if necessary the dumb pointer.

Definition at line 173 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__destroy(), gum::RefPtr< Val >::__refcount, and gum::RefPtr< Val >::__val.

                                {
    // for debugging purposes
    GUM_DESTRUCTOR(RefPtr);
    __destroy(__refcount, __val);
  }

Here is the call graph for this function:

RefPtr() [4/4]

template<typename Val>

template<typename DownVal >

INLINE gum::RefPtr< Val >::RefPtr

(

const RefPtr< DownVal > &

from

)

Definition at line 57 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__refcount.

                                                            :
      __val(from.__val), __refcount(from.__refcount) {
    // for debugging purposes
    GUM_CONS_CPY(RefPtr);

    if (__refcount) ++*__refcount;
  }

Member Function Documentation

__destroy()

template<typename Val >

INLINE void gum::RefPtr< Val >::__destroy ( unsigned int *  count, Val *  v  )

private

A function to remove the content of the smart pointer, if any.

Definition at line 68 of file refPtr_tpl.h.

Referenced by gum::RefPtr< Val >::clear(), gum::RefPtr< Val >::operator=(), and gum::RefPtr< Val >::~RefPtr().

                                                                  {
    if (count) {
      if (*count == 1U) {
        // do not change the order of the deletes (this prevents memory leaks
        // when
        // the delete of v fails (note that this should probably never happen))
        delete count;
        delete v;
      } else
        --*count;
    }
  }

Here is the caller graph for this function:

__refCountPtr()

template<typename Val >

INLINE unsigned int * gum::RefPtr< Val >::__refCountPtr ( ) const

private

A function to return the refcount pointer.

Definition at line 253 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__refcount.

                                                          {
    return __refcount;
  }

clear()

template<typename Val >

INLINE void gum::RefPtr< Val >::clear

(

)

Makes the smart pointer point to 0.

If necessary, the dumb pointer previously pointed to by the RefPtr is deallocated. In this case, an exception may be thrown by the destructor of the object pointed to. But, even in this case, the RefPtr guarrantees that after the completion of this method, the RefPtr will point toward 0.

Definition at line 230 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__destroy(), gum::RefPtr< Val >::__refcount, and gum::RefPtr< Val >::__val.

                                   {
    // keep track of the old pointer and reference count
    unsigned int* old_refcount = __refcount;
    Val*          old_val = __val;
    // set properly the dumb pointer and its refcount
    __val = 0;
    __refcount = 0;
    // now try to dereference the old dumb pointer
    __destroy(old_refcount, old_val);
  }

Here is the call graph for this function:

operator bool()

template<typename Val >

INLINE gum::RefPtr< Val >::operator bool

(

)

const

Checks whether a RefPtr points toward something.

This method enables writing code like if (refptr) perform_operation()

Definition at line 223 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__val.

                                            {
    return (__val != 0);
  }

operator!=()

template<typename Val >

INLINE bool gum::RefPtr< Val >::operator!=

(

const RefPtr< Val > &

from

)

const

Checks whether two RefPtr<Val> are smart pointers for different elements.

Returns true if either the dumb pointers the smart pointers encapsulate are different or the reference counters are different (i.e., the smart pointers are not related through copy operators).

Parameters

from	The gum::RefPtr to test for inequality.

Returns

Returns true if this and from differ.

Definition at line 189 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__refcount.

                                                                       {
    return from.__refcount != __refcount;
  }

operator*() [1/2]

template<typename Val >

INLINE Val & gum::RefPtr< Val >::operator*

(

)

Dereferencing operator.

This operator is provided for convenience but you should prefer using operator -> as this is the syntax you would use with the dumb pointer. Note however that it might be useful for built-in types such as int.

Returns

Returns a reference over the value referenced by this gum::RefPtr.

Exceptions

NullElement

Raised whenever the RefPtr points to 0.

Definition at line 196 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__val, and GUM_ERROR.

                                       {
    if (!__val) { GUM_ERROR(NullElement, "dereferencing a nullptr pointer"); }

    return *__val;
  }

operator*() [2/2]

template<typename Val >

INLINE const Val & gum::RefPtr< Val >::operator*

(

)

const

Const dereferencing operator.

This operator is provided for convenience but you should prefer using operator -> as this is the syntax you would use with the dumb pointer. Note however that it might be useful for built-in types such as int.

Returns

Returns a constant reference over the value referenced by this gum::RefPtr.

Exceptions

NullElement

Raised whenever the RefPtr points to 0.

Definition at line 205 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__val, and GUM_ERROR.

                                                   {
    if (!__val) { GUM_ERROR(NullElement, "dereferencing a nullptr pointer"); }

    return *__val;
  }

operator->()

template<typename Val >

INLINE Val * gum::RefPtr< Val >::operator->

(

)

const

Dereferencing operator.

This operator allows developers to write code like refptr->member().

Returns

Returns a pointer over the value referenced by this gum::RefPtr.

Exceptions

NullElement

Raised whenever the smart pointer points toward 0.

Definition at line 214 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__val, and GUM_ERROR.

                                              {
    if (!__val) { GUM_ERROR(NullElement, "dereferencing a nullptr pointer"); }

    return __val;
  }

operator=() [1/4]

template<typename Val>

template<typename DownVal >

INLINE RefPtr< Val >& gum::RefPtr< Val >::operator=

(

const RefPtr< DownVal > &

from

)

Definition at line 151 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__destroy(), gum::RefPtr< Val >::__refcount, and gum::RefPtr< Val >::__val.

                                                                              {
    // for debugging purposes
    GUM_OP_CPY(RefPtr);
    // keep track of the current refcount and dumb pointer
    unsigned int* old_refcount = __refcount;
    Val*          old_val = __val;

    // perform the copy
    __refcount = from.__refcount;
    __val = from.__val;

    if (__refcount) ++*__refcount;

    // now try to dereference the old dumb pointer
    __destroy(old_refcount, old_val);

    return *this;
  }

Here is the call graph for this function:

operator=() [2/4]

template<typename Val >

INLINE RefPtr< Val > & gum::RefPtr< Val >::operator=

(

const RefPtr< Val > &

from

)

Copy operator.

The operator= may throw exceptions when the dumb pointer previously pointed to by the RefPtr is deallocated (that is, the destructor of the object pointed to may throw an exception). However, even when this occurs, the RefPtr guarrantees that the copy operation is correctly performed, that is, after the completion of the function, the RefPtr points to the same element as from.

Parameters

from	The smart pointer we wish to make a copy.

Returns

Returns this gum::RefPtr.

Definition at line 84 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__destroy(), gum::RefPtr< Val >::__refcount, and gum::RefPtr< Val >::__val.

                                                                          {
    // avoid self assignment
    if (__val != from.__val) {
      // for debugging purposes
      GUM_OP_CPY(RefPtr);

      // keep track of the current refcount and dumb pointer
      unsigned int* old_refcount = __refcount;
      Val*          old_val = __val;

      // perform the copy
      __refcount = from.__refcount;
      __val = from.__val;

      if (__refcount) ++*__refcount;

      // now try to dereference the old dumb pointer
      __destroy(old_refcount, old_val);
    }

    return *this;
  }

Here is the call graph for this function:

operator=() [3/4]

template<typename Val >

INLINE RefPtr< Val > & gum::RefPtr< Val >::operator=

(

Val *

from

)

Copy operator.

The operator= may throw exceptions when the dumb pointer previously pointed to by the RefPtr is deallocated (that is, the destructor of the object pointed to may throw an exception). However, even when this occurs, the RefPtr guarrantees that its state is coherent: either it could succeed to encapsulate the dumb pointer and this one is referenced once, or even encapsulating the new pointer failed and the RefPtr points toward the 0 pointer.

Parameters

from	the dumb pointer we wish to encapsulate.

Returns

Returns this gum::RefPtr.

Definition at line 110 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__destroy(), gum::RefPtr< Val >::__refcount, and gum::RefPtr< Val >::__val.

                                                          {
    // avoid self assignment
    if (__val != from) {
      // for debugging purposes
      GUM_OP_CPY(RefPtr);

      // keep track of the current refcount and dumb pointer
      unsigned int* old_refcount = __refcount;
      Val*          old_val = __val;

      // perform the copy
      try {
        if (from)
          __refcount = new unsigned int(1U);
        else
          __refcount = 0;

        __val = from;
      } catch (std::bad_alloc&) {
        if (*old_refcount == 1) {
          __val = from;
          delete old_val;
          return *this;
        }

        __refcount = 0;
        __val = 0;
        throw;
      }

      // now try to dereference the old dumb pointer
      __destroy(old_refcount, old_val);
    }

    return *this;
  }

Here is the call graph for this function:

operator=() [4/4]

template<typename Val>

template<typename DownVal >

RefPtr< Val >& gum::RefPtr< Val >::operator=

(

const RefPtr< DownVal > &

from

)

Copy operator for downcastable pointers.

The operator= may throw exceptions when the dumb pointer previously pointed to by the RefPtr is deallocated (that is, the destructor of the object pointed to may throw an exception). However, even when this occurs, the RefPtr guarrantees that the copy operation is correctly performed, that is, after the completion of the function, the RefPtr points to the same element as from.

Template Parameters

DownVal

The downcastable type.

Parameters

from	the smart pointer we wish to make a copy.

Returns

Returns this gum::RefPtr.

operator==()

template<typename Val >

INLINE bool gum::RefPtr< Val >::operator==

(

const RefPtr< Val > &

from

)

const

Checks whether two RefPtr<Val> are smart pointers for the same element.

"Pointing toward the same element" is a little ambiguous: it does not mean that the smart pointers are pointing toward the same Val instance as several RefPtr<Val> created by the constructor with *val may point toward the same val element while being unrelated (they do not share the same reference). Instead, it means that the two smart pointers share the same reference counter, i.e., that at least one of the two smarts pointers has been created using the copy operator. As a consequence both pointers point toward the same Val instance (but the converse is false).

Parameters

from	The gum::RefPtr to test for equality.

Returns

Returns true if this and from are equal.

Definition at line 182 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__refcount.

                                                                       {
    return from.__refcount == __refcount;
  }

refCount()

template<typename Val >

INLINE unsigned int gum::RefPtr< Val >::refCount

(

)

const

Returns the number of smart pointer referencing the contained pointer.

Definition at line 244 of file refPtr_tpl.h.

References gum::RefPtr< Val >::__refcount.

                                                    {
    if (__refcount == 0) return 0;

    return *__refcount;
  }

Friends And Related Function Documentation

RefPtr

template<typename Val>

template<typename T >

friend class RefPtr

friend

A friend to allow downcastings.

Definition at line 331 of file refPtr.h.

HashFunc

template<typename Val>

template<typename T >

friend class HashFunc

friend

A friend for hashing quickly ref pointers.

Definition at line 335 of file refPtr.h.

swap

template<typename Val>

void swap ( RefPtr< Val > &  ptr1, RefPtr< Val > &  ptr2  )

friend

The swap function must access to gum::RefPtr private parts.

Definition at line 260 of file refPtr_tpl.h.

                                                      {
    // save from's content
    Val*          tmp_val = ptr2.__val;
    unsigned int* tmp_refcount = ptr2.__refcount;
    // modify from's content
    ptr2.__refcount = ptr1.__refcount;
    ptr2.__val = ptr1.__val;
    // modify this's content
    ptr1.__val = tmp_val;
    ptr1.__refcount = tmp_refcount;
  }

Member Data Documentation

__refcount

template<typename Val>

unsigned int* gum::RefPtr< Val >::__refcount

private

A reference counter on *val.

Definition at line 341 of file refPtr.h.

Referenced by gum::RefPtr< Val >::__refCountPtr(), gum::RefPtr< Val >::clear(), gum::RefPtr< Val >::operator!=(), gum::RefPtr< Val >::operator=(), gum::RefPtr< Val >::operator==(), gum::RefPtr< Val >::refCount(), gum::RefPtr< Val >::RefPtr(), gum::swap(), and gum::RefPtr< Val >::~RefPtr().

__val

template<typename Val>

Val* gum::RefPtr< Val >::__val

private

The dumb pointer encapsulated into the "smart" pointer.

Definition at line 338 of file refPtr.h.

Referenced by gum::RefPtr< Val >::clear(), gum::RefPtr< Val >::operator bool(), gum::RefPtr< Val >::operator*(), gum::RefPtr< Val >::operator->(), gum::RefPtr< Val >::operator=(), gum::swap(), and gum::RefPtr< Val >::~RefPtr().

---

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

• agrum/core/refPtr.h
• agrum/core/refPtr_tpl.h