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/tools/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 116 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 35 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

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

Here is the call graph for this function:

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 44 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                        :
      val__(from.val__), refcount__(from.refcount__) {
    // for debugging purposes
    GUM_CONS_CPY(RefPtr);

    if (refcount__) ++*refcount__;
  }

Here is the call graph for this function:

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 172 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                {
    // 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 56 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                            :
      val__(from.val__), refcount__(from.refcount__) {
    // for debugging purposes
    GUM_CONS_CPY(RefPtr);

    if (refcount__) ++*refcount__;
  }

Here is the call graph for this function:

Member Function Documentation

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 229 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                   {
    // 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:

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 67 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                  {
    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 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 222 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                            {
    return (val__ != 0);
  }

Here is the call graph for this function:

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 188 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                       {
    return from.refcount__ != refcount__;
  }

Here is the call graph for this function:

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 195 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

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

    return *val__;
  }

Here is the call graph for this function:

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 204 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

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

    return *val__;
  }

Here is the call graph for this function:

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 213 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

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

    return val__;
  }

Here is the call graph for this function:

operator=() [1/4]

template<typename Val >

template<typename DownVal >

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

(

const RefPtr< DownVal > &

from

)

Definition at line 150 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                              {
    // 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 83 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                          {
    // 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 109 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                          {
    // 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 181 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                                       {
    return from.refcount__ == refcount__;
  }

Here is the call graph for this function:

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 243 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                    {
    if (refcount__ == 0) return 0;

    return *refcount__;
  }

Here is the call 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 252 of file refPtr_tpl.h.

References gum::Set< Key, Alloc >::emplace().

                                                          {
    return refcount__;
  }

Here is the call graph for this function:

Friends And Related Function Documentation

RefPtr

template<typename Val >

template<typename T >

friend class RefPtr

friend

A friend to allow downcastings.

Definition at line 330 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 334 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 259 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 340 of file refPtr.h.

val__

template<typename Val >

Val* gum::RefPtr< Val >::val__

private

The dumb pointer encapsulated into the "smart" pointer.

Definition at line 337 of file refPtr.h.

---

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

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