ObjContainer< T_Obj > Class Template Reference

Helper classes to manage shared objects in a scope. More...

#include <ObjContainer.h>

Collaboration diagram for ObjContainer< T_Obj >:

Public Member Functions
	ObjContainer (unsigned int min_size=0)
	~ObjContainer () noexcept(false)
bool	isValid (ObjRef ref) const
std::pair< short, bool >	search (T_Obj *obj) const
unsigned short	size () const
	Return the current number of slots on the container. More...

Protected Member Functions
ObjRef	registerObj (T_Obj &obj)
	Manage an external object. More...
ObjRef	registerObj (T_Obj *obj)
	manage a new object. More...
ObjRef	share (ObjRef ref)
	Increase the share count of a given object. More...
void	drop (ObjRef &ref)
	Decrease the share count of the referenced object and eventually destroy it. More...
const T_Obj *	get (ObjRef ref) const
	Get a pointer to a managed object. More...
T_Obj *	get (ObjRef ref)
	Get a pointer to a managed object. More...
T_Obj *	release (ObjRef ref)
	Remove ownership over the given object from the container. More...
bool	isOwned (ObjRef ref) const
	Return true if this container owns the object. More...
bool	isShared (ObjRef ref) const
	Return true if the object is referred to by more than one ObjPtr. More...
bool	isExtern (ObjRef ref) const
	Return true if the object is external i.e. More...
short	count (ObjRef ref) const
ObjRef	find (T_Obj *obj) const
	Search for an object in the container. More...
void	ensureValidity (ObjRef ref) const
	Will throw an exception if the reference is not valid. More...
void	ensureExists (ObjRef ref) const
	Will throw an exception if the referenced object does not exist. More...
void	checkCapacity ()
	Will throw an exception if the maximum capacity of the container is exceeded. More...
ObjRef	registerObj (T_Obj *obj, short initial_count)
	Register an object with a given state (external, released, shared) More...

Protected Attributes
std::vector< std::pair< T_Obj *, short > >	m_objs
	The storage for the object pointers. More...
unsigned short	m_freeIdx =std::numeric_limits<unsigned short>::max()

Static Protected Attributes
constexpr static short	s_externalObj = -2
	"share count" of external objects More...
constexpr static short	s_releasedObj = -1
	"share count" of released objects More...

Friends
template<class T_Obj_ >
class	ObjPtr

Detailed Description

template<class T_Obj>
class ObjContainer< T_Obj >

Helper classes to manage shared objects in a scope.

Container for managed objects.

Implements smart pointer which allow mixing external i.e. unmanaged resources, resources which are shared or released ( out of the scope.). The pointer to all objects are stored in a central container which tags external and released resources and performs reference counting for shared resources. Non external or released resources are freed if the container goes out scope.

The template cloneObj may have to be specialised if the copy constructor of the container object base class does not properly clone the managed objects.

Objects can be either external (unmanaged), released (ownership changed to external), or shared. The methods of this class are mostly not meant to be used directly but rather through ObjPtr. Managed objects are referred to by ObjPtr and references (ObjRef) to the objects can be passed functions. While ObjPtr guarantee that objects stay alive, the references ObjRef do not provide such guarantees.

For example:

* using Cont = ObjContainer<...>;
* using Ptr  = ObjPtr<...>;
* using Ref  = ObjRef<...>;
* ... inner(Cont &cont, Ref ref) {
*    Ptr b_ptr(cont,ref);
*    ...
* }
* ... outer() {
*    Cont cont;
*    Ptr a_ptr(cont, ...);
*    inner(cont, a_ptr.index());
*    ...
* }
* 

Lifetime guarantee of object referred to by a_ptr in outer, provided because the instance a_ptr will stay alive while inner is called, thus ref will point to a valid object in the container.

This will not work:

* ... inner(Cont &cont, Ref ref) {
*    Ptr b_ptr(cont,ref);
*    ...
* }
* ... outer() {
*    Cont cont;
*    Ref dangling_ref;
*    {
*      Ptr a_ptr(cont, ...);
*      dangling_ref=a_ptr.index(); // BAD: dangling_ref has wider scope than a_ptr
*    }
*    // object referred to by a_ptr / dangling_ref got deleted
*    // thus dangling_ref now refers to an invalid object.
*    inner(cont, dangling_ref);
*    ...
* }
* 

Definition at line 30 of file ObjContainer.h.

Constructor & Destructor Documentation

ObjContainer()

template<class T_Obj >

ObjContainer< T_Obj >::ObjContainer ( unsigned int  min_size = 0 )

inline

Definition at line 215 of file ObjContainer.h.

{ m_objs.reserve(min_size); }

~ObjContainer()

template<class T_Obj >

ObjContainer< T_Obj >::~ObjContainer ( )

inlinenoexcept

Definition at line 217 of file ObjContainer.h.

                                   {
      for (std::pair<T_Obj *, short> &elm : m_objs) {
         if (elm.second>0) {
            this->throwObjectStillAlive(elm.first,static_cast<size_t>(elm.second));
         }
         if (elm.first && elm.second>0) {
            this->throwObjectStillAlive(elm.first,static_cast<size_t>(elm.second));
         }
      }
   }

Member Function Documentation

checkCapacity()

template<class T_Obj >

void ObjContainer< T_Obj >::checkCapacity ( )

inlineprotected

Will throw an exception if the maximum capacity of the container is exceeded.

Definition at line 412 of file ObjContainer.h.

                        {
      if (m_objs.size() >= std::numeric_limits<unsigned short>::max()) {
         this->throwMaximumCapacitiyExceeded(m_objs.size());
      }
   }

count()

template<class T_Obj >

short ObjContainer< T_Obj >::count ( ObjRef  ref ) const

inlineprotected

Definition at line 374 of file ObjContainer.h.

                                 {
     return m_objs[ref.idx() ].second;
   }

drop()

template<class T_Obj >

void ObjContainer< T_Obj >::drop ( ObjRef &  ref )

inlineprotected

Decrease the share count of the referenced object and eventually destroy it.

Will destroy "shared" objects if the share count drops to zero, but external or released objects will not be touched.

Definition at line 289 of file ObjContainer.h.

                            {
      ensureValidity(ref);
      switch(m_objs[ref.idx()].second)  {
      case s_externalObj: { return ; }
 
      case s_releasedObj: { this->warnShareDropAfterRelease( ref.idx() );
                            return ; }
 
      case 0:             this->throwObjectAlreadyDeleted( ref.idx());
                          [[fallthrough]]; // throws exception
 
      default:            { break; }
      }
 
      if (--(m_objs[ref.idx()].second) == 0) {
         T_Obj *obj=m_objs[ref.idx()].first;
         delete obj;
         m_objs[ref.idx()].first=nullptr;
         assert(!find(obj)); // Ensure that deleted objects are not referenced anymore
         if (m_freeIdx == std::numeric_limits<unsigned short>::max()) {
            m_freeIdx=ref.idx();
         }
         ref= ObjRef();
      }
   }

ensureExists()

template<class T_Obj >

void ObjContainer< T_Obj >::ensureExists ( ObjRef  ref ) const

inlineprotected

Will throw an exception if the referenced object does not exist.

Definition at line 405 of file ObjContainer.h.

                                        {
      ensureValidity(ref);
      if (m_objs[ref.idx() ].second == 0) { this->throwObjectAlreadyDeleted( ref.idx()); }
   }

ensureValidity()

template<class T_Obj >

void ObjContainer< T_Obj >::ensureValidity ( ObjRef  ref ) const

inlineprotected

Will throw an exception if the reference is not valid.

Definition at line 399 of file ObjContainer.h.

                                          {
      if (!isValid(ref)) this->throwInvalidObject( ref.idx(), m_objs.size());
   }

find()

template<class T_Obj >

ObjRef ObjContainer< T_Obj >::find ( T_Obj *  obj ) const

inlineprotected

Search for an object in the container.

Returns

a valid reference if the object is found or otherwise an invalid reference.

Definition at line 382 of file ObjContainer.h.

                                   {
      for (typename std::vector< std::pair<T_Obj *, short> >::const_reverse_iterator
              iter =m_objs.rbegin();
           iter != m_objs.rend();
           ++iter) {
         if (iter->first == obj) {
            assert( m_objs.at(m_objs.rend()-iter-1).first == obj);
             ObjRef ref( static_cast<unsigned short>(m_objs.rend()-iter-1) ); // @TODO std::distance ?
            ensureValidity(ref);
            return ref;
         }
      }
      return  ObjRef();
   }

get() [1/2]

template<class T_Obj >

T_Obj* ObjContainer< T_Obj >::get ( ObjRef  ref )

inlineprotected

Get a pointer to a managed object.

Parameters

ref	reference to the object.

Exceptions

if	the reference is invalid or the object does not exist.

Definition at line 328 of file ObjContainer.h.

                             {
       ensureExists(ref);
       return m_objs[ref.idx()].first;
    }

get() [2/2]

template<class T_Obj >

const T_Obj* ObjContainer< T_Obj >::get ( ObjRef  ref ) const

inlineprotected

Get a pointer to a managed object.

Parameters

ref	reference to the object.

Exceptions

if	the reference is invalid or the object does not exist.

Definition at line 319 of file ObjContainer.h.

                                        {
      ensureExists(ref);
      return m_objs[ref.idx()].first;
   }

isExtern()

template<class T_Obj >

bool ObjContainer< T_Obj >::isExtern ( ObjRef  ref ) const

inlineprotected

Return true if the object is external i.e.

not owned by this container.

Definition at line 370 of file ObjContainer.h.

                                     {
      return count(ref) == s_externalObj;
   }

isOwned()

template<class T_Obj >

bool ObjContainer< T_Obj >::isOwned ( ObjRef  ref ) const

inlineprotected

Return true if this container owns the object.

Definition at line 358 of file ObjContainer.h.

                                    {
      return count(ref) == 1;
   }

isShared()

template<class T_Obj >

bool ObjContainer< T_Obj >::isShared ( ObjRef  ref ) const

inlineprotected

Return true if the object is referred to by more than one ObjPtr.

Definition at line 364 of file ObjContainer.h.

                                     {
      return count(ref) > 1;
   }

isValid()

template<class T_Obj >

bool ObjContainer< T_Obj >::isValid ( ObjRef  ref ) const

inline

Definition at line 228 of file ObjContainer.h.

                                   {
      return ref.idx() < m_objs.size() && m_objs[ref.idx()].first; // @TODO the latter test should not be necessary
   }

registerObj() [1/3]

template<class T_Obj >

ObjRef ObjContainer< T_Obj >::registerObj ( T_Obj &  obj )

inlineprotected

Manage an external object.

Parameters

obj	to an external object. The ownership is not taken by the container.

Definition at line 247 of file ObjContainer.h.

                                   {
      return registerObj(&obj, s_externalObj);
   }

registerObj() [2/3]

template<class T_Obj >

ObjRef ObjContainer< T_Obj >::registerObj ( T_Obj *  obj )

inlineprotected

manage a new object.

Parameters

obj	the object to be managed. This passes ownership to the container.

Definition at line 255 of file ObjContainer.h.

                                   {
      return registerObj(obj, 0);
   }

registerObj() [3/3]

template<class T_Obj >

ObjRef ObjContainer< T_Obj >::registerObj ( T_Obj *  obj, short  initial_count  )

inlineprotected

Register an object with a given state (external, released, shared)

Definition at line 420 of file ObjContainer.h.

                                                        {
      if (!obj) return  ObjRef{};
      checkCapacity();
 
       ObjRef ref = find(obj);
      if (isValid(ref))  {
         switch(m_objs.at(ref.idx()).second) {
         case 0: {
            break;
         }
         case s_releasedObj:
            if (initial_count == s_externalObj) {
               break;
            }
            [[fallthrough]];
         default:
            this->throwObjectExistsAlready( obj);
         }
         //         return ref;
      }
      if (m_freeIdx == std::numeric_limits<unsigned short>::max() && m_objs.size() >= m_objs.capacity()) {
         for (typename std::vector< std::pair<T_Obj *, short> >::const_reverse_iterator
                 iter =m_objs.rbegin();
              iter != m_objs.rend();
              ++iter) {
            if (iter->second==0) {
               m_freeIdx=m_objs.rend()-iter-1;
            }
         }
      }
      if (m_freeIdx == std::numeric_limits<unsigned short>::max()) {
         ref=ObjRef(static_cast<unsigned short>(m_objs.size()));
         m_objs.push_back(std::make_pair(obj, initial_count));
      } else {
         m_objs[m_freeIdx] = std::make_pair( obj,initial_count);
         ref=ObjRef(m_freeIdx);
         m_freeIdx = std::numeric_limits<unsigned short>::max();
      }
      ensureValidity(ref);
      return ref;
   }

release()

template<class T_Obj >

T_Obj* ObjContainer< T_Obj >::release ( ObjRef  ref )

inlineprotected

Remove ownership over the given object from the container.

Parameters

ref	reference to the object.

Exceptions

will

throw an exception if the reference is invalid. Will remove ownership over the referenced object from the container. The object is still accessible like an external object. Thus, it is up to the user to ensure that released objects remain alive at least as long as the object container. If the object is an external object or was released already a clone is created.

Definition at line 341 of file ObjContainer.h.

                                {
      ensureValidity(ref);
      switch (m_objs[ref.idx() ].second) {
      case 0: this->throwObjectAlreadyDeleted( ref.idx());
              [[fallthrough]]; // will not fall through, because of exception
      case s_releasedObj:
              [[fallthrough]]; // indeed, should also clone the object
      case s_externalObj:   return cloneObj(m_objs[ref.idx()].first);
      default:
         m_objs[ref.idx()].second = s_releasedObj;
        
         return m_objs[ref.idx()].first;
      }
   }

search()

template<class T_Obj >

std::pair<short, bool > ObjContainer< T_Obj >::search ( T_Obj *  obj ) const

inline

Definition at line 233 of file ObjContainer.h.

                                                  {
       ObjRef ref(find(obj));
      return std::make_pair( ref ? m_objs[ref.idx()].second : short{},  ref.isValid() );
   }

share()

template<class T_Obj >

ObjRef ObjContainer< T_Obj >::share ( ObjRef  ref )

inlineprotected

Increase the share count of a given object.

Parameters

ref	a reference to the object that is to be shared.

Definition at line 262 of file ObjContainer.h.

                              {
      ensureValidity(ref);
      switch(m_objs[ref.idx()].second)  {
      case s_externalObj: { return ref; }
 
      case s_releasedObj: { this->warnShareDropAfterRelease( ref.idx() );
                            
                            return ref; }
 
      case 0:             if (!m_objs[ref.idx()].first) {this->throwObjectAlreadyDeleted( ref.idx());}
                          [[fallthrough]]; // throws exception
 
      default:            { break; }
      }
 
      if (m_objs[ref.idx()].second >= std::numeric_limits<short>::max()) {
         this->throwMaximumNumberOfSharesExceeded(std::numeric_limits<short>::max()); // clone object and add new slot ?
      }
      ++(m_objs[ref.idx()].second);
 
      return ref;
   }

size()

template<class T_Obj >

unsigned short ObjContainer< T_Obj >::size ( ) const

inline

Return the current number of slots on the container.

Not each slot may point to an object.

Definition at line 241 of file ObjContainer.h.

{ return static_cast<unsigned short>(m_objs.size()); }

Friends And Related Function Documentation

ObjPtr

template<class T_Obj >

template<class T_Obj_ >

friend class ObjPtr

friend

Definition at line 213 of file ObjContainer.h.

Member Data Documentation

m_freeIdx

template<class T_Obj >

unsigned short ObjContainer< T_Obj >::m_freeIdx =std::numeric_limits<unsigned short>::max()

protected

Definition at line 466 of file ObjContainer.h.

m_objs

template<class T_Obj >

std::vector< std::pair<T_Obj *, short> > ObjContainer< T_Obj >::m_objs

protected

The storage for the object pointers.

Definition at line 465 of file ObjContainer.h.

s_externalObj

template<class T_Obj >

constexpr static short ObjContainer< T_Obj >::s_externalObj = -2

staticconstexprprotected

"share count" of external objects

Definition at line 462 of file ObjContainer.h.

s_releasedObj

template<class T_Obj >

constexpr static short ObjContainer< T_Obj >::s_releasedObj = -1

staticconstexprprotected

"share count" of released objects

Definition at line 463 of file ObjContainer.h.

---

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

• ObjContainer.h