Smart pointers. More...

#include <agrum/base/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.
	RefPtr (const RefPtr< Val > &from)
	Copy constructor.
template<typename DownVal>
	RefPtr (const RefPtr< DownVal > &from)
	Copy constructor for downcastable pointers.
	~RefPtr ()
	Class destructor.
Accessors / Modifiers
	operator bool () const
	Checks whether a RefPtr points toward something.
void	clear ()
	Makes the smart pointer point to 0.
unsigned int	refCount () const
	Returns the number of smart pointer referencing the contained pointer.
Operators
RefPtr< Val > &	operator= (const RefPtr< Val > &from)
	Copy operator.
RefPtr< Val > &	operator= (Val *from)
	Copy operator.
template<typename DownVal>
RefPtr< Val > &	operator= (const RefPtr< DownVal > &from)
	Copy operator for downcastable pointers.
bool	operator== (const RefPtr< Val > &from) const
	Checks whether two RefPtr<Val> are smart pointers for the same element.
bool	operator!= (const RefPtr< Val > &from) const
	Checks whether two RefPtr<Val> are smart pointers for different elements.
Val *	operator-> () const
	Dereferencing operator.
Val &	operator* ()
	Dereferencing operator.
const Val &	operator* () const
	Const dereferencing operator.

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

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

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 )

gum::RefPtr::RefPtr

friend class RefPtr

A friend to allow downcastings.

Definition refPtr.h:351

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;

gum::RefPtr::clear
void clear()
Makes the smart pointer point to 0.
Definition refPtr_tpl.h:239

Template Parameters

Val	The type referenced by the gum::RefPtr.

Definition at line 136 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 56 of file refPtr_tpl.h.

                                     : _val_(v), _refcount_(v ? new unsigned int(1U) : 0) {
    GUM_CONSTRUCTOR(RefPtr);
  }

References RefPtr, _refcount_, and _val_.

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

                                                        :
      _val_(from._val_), _refcount_(from._refcount_) {
    GUM_CONS_CPY(RefPtr);
 
    if (_refcount_) ++*_refcount_;
  }

References RefPtr, _refcount_, and _val_.

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.

References RefPtr.

Here is the call graph for this function:

◆ ~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 183 of file refPtr_tpl.h.

                                {
    GUM_DESTRUCTOR(RefPtr);
    _destroy_(_refcount_, _val_);
  }

References RefPtr, _destroy_(), _refcount_, and _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 74 of file refPtr_tpl.h.

                                                            :
      _val_(from._val_), _refcount_(from._refcount_) {
    GUM_CONS_CPY(RefPtr);
 
    if (_refcount_) ++*_refcount_;
  }

References RefPtr, _refcount_, and _val_.

Here is the call graph for this function:

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

                                                                  {
    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;
    }
  }

Referenced by ~RefPtr(), clear(), operator=(), operator=(), and operator=().

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

                                                          {
    return _refcount_;
  }

References _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 239 of file refPtr_tpl.h.

                                   {
    // 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);
  }

References _destroy_(), _refcount_, and _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 232 of file refPtr_tpl.h.

                                            {
    return (_val_ != 0);
  }

References RefPtr, and _val_.

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

                                                                     {
    return from._refcount_ != _refcount_;
  }

References RefPtr, and _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 205 of file refPtr_tpl.h.

                                       {
    if (!_val_) { GUM_ERROR(NullElement, "dereferencing a nullptr pointer") }
 
    return *_val_;
  }

References _val_, and GUM_ERROR.

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

                                                   {
    if (!_val_) { GUM_ERROR(NullElement, "dereferencing a nullptr pointer") }
 
    return *_val_;
  }

References _val_, and GUM_ERROR.

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

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

References _val_, and GUM_ERROR.

◆ operator=() [1/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.

References RefPtr.

Here is the call graph for this function:

◆ operator=() [2/4]

template<typename Val>

template<typename DownVal>

INLINE RefPtr< Val > & gum::RefPtr< Val >::operator= ( const RefPtr< DownVal > & from )

Definition at line 162 of file refPtr_tpl.h.

                                                                            {
    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;
  }

References RefPtr, _destroy_(), _refcount_, and _val_.

Here is the call graph for this function:

◆ operator=() [3/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 99 of file refPtr_tpl.h.

                                                                        {
    // avoid self assignment
    if (_val_ != from._val_) {
      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;
  }

References RefPtr, _destroy_(), _refcount_, and _val_.

Here is the call graph for this function:

◆ operator=() [4/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 124 of file refPtr_tpl.h.

                                                        {
    // avoid self assignment
    if (_val_ != from) {
      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;
  }

References RefPtr, _destroy_(), _refcount_, and _val_.

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

                                                                     {
    return from._refcount_ == _refcount_;
  }

References RefPtr, and _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 253 of file refPtr_tpl.h.

                                                    {
    if (_refcount_ == 0) return 0;
 
    return *_refcount_;
  }

References _refcount_.

◆ RefPtr

template<typename Val>

template<typename T>

friend class RefPtr

friend

A friend to allow downcastings.

Definition at line 351 of file refPtr.h.

References RefPtr.

Referenced by RefPtr, RefPtr(), RefPtr(), RefPtr(), ~RefPtr(), operator bool(), operator!=(), operator=(), operator=(), operator=(), operator==(), and swap.

◆ HashFunc

template<typename Val>

template<typename T>

friend class HashFunc

friend

A friend for hashing quickly ref pointers.

Definition at line 355 of file refPtr.h.

References HashFunc.

Referenced by HashFunc.

◆ 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 269 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;
  }

References RefPtr, _refcount_, and _val_.

Member Data Documentation

◆ _refcount_

template<typename Val>

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

private

A reference counter on *val.

Definition at line 361 of file refPtr.h.

Referenced by RefPtr(), RefPtr(), RefPtr(), ~RefPtr(), _refCountPtr_(), clear(), operator!=(), operator=(), operator=(), operator=(), operator==(), refCount(), and swap.

◆ _val_

template<typename Val>

Val* gum::RefPtr< Val >::_val_

private

The dumb pointer encapsulated into the "smart" pointer.

Definition at line 358 of file refPtr.h.

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

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

agrum/base/core/refPtr.h
agrum/base/core/refPtr_tpl.h

Public Member Functions

Friends

Internals

Detailed Description

Constructor & Destructor Documentation

◆ RefPtr() [1/4]

◆ RefPtr() [2/4]

◆ RefPtr() [3/4]

◆ ~RefPtr()

◆ RefPtr() [4/4]

Member Function Documentation

◆ _destroy_()

◆ _refCountPtr_()

◆ clear()

◆ operator bool()

◆ operator!=()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator->()

◆ operator=() [1/4]

◆ operator=() [2/4]

◆ operator=() [3/4]

◆ operator=() [4/4]

◆ operator==()

◆ refCount()

Friends And Related Symbol Documentation

◆ RefPtr

◆ HashFunc

◆ swap

Member Data Documentation

◆ _refcount_

◆ _val_