gzReference.h

Go to the documentation of this file.

//*****************************************************************************
// File         : gzReference.h
// Module       : gzBase
// Description  : Class definition of reference handle
// Author       : Anders Modén      
// Product      : GizmoBase 2.1.1
//      
// Copyright © 2003- Saab Training Systems AB, Sweden   
//          
// NOTE:    GizmoBase is a platform abstraction utility layer for C++. It contains 
//          design patterns and C++ solutions for the advanced programmer.
//
//
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created file    
//
//******************************************************************************
#ifndef __GZ_REFERENCE_H__
#define __GZ_REFERENCE_H__

#include "gzMemory.h"
#include "gzTemplates.h"
#include "gzDebug.h"
#include "gzType.h"


enum gzCopyMode
{   
    GZ_CLONE_NO_SHARE           = (0),  // Node share modes 
    GZ_CLONE_SHARE_ALL          = 0xFFFFFFFFUL, 
};

GZ_USE_BIT_LOGIC(gzCopyMode);

//******************************************************************************
// Class    : gzReference
//                                  
// Purpose  : Holds reference count to objects
//                                  
// Notes    : - 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created 
//                                  
//******************************************************************************

class  GZ_BASE_EXPORT gzReference : public gzSharedMemory , public gzTypeInterface
{
public:
    GZ_DECLARE_TYPE_INTERFACE;      

    gzReference();

    gzReference(const gzReference &copy);

    gzReference &operator=(const gzReference &copy);

    virtual ~gzReference();
    

    virtual gzReference* clone() const;

public:

    // ----- Class dependant copy behaviour --------------------------
    // Each class can override deep copy to implement shared resources
    // ---------------------------------------------------------------


    const gzCopyMode &  getCopyMode() const { return m_copyMode; }


    virtual gzVoid  setCopyMode(const gzCopyMode & mode) { m_copyMode=mode; }
    

    virtual gzBool  useDeepCopy() { return m_copyMode==GZ_CLONE_NO_SHARE; } // Default behaviour is to deep copy


    virtual gzVoid  ref();


    virtual gzVoid  unref();


    virtual gzUInt  unrefNoDelete();


    virtual gzBool  checkDelete();

    virtual gzUInt  getRef() const { return _refCount; }

protected:

    gzUInt          _refCount;

private:

    // Private utility function

    static gzVoid   throwFatalException( const char * str1 , const char * str2 = NULL);

    gzCopyMode      m_copyMode; // class dependant
};


//******************************************************************************
// Function : gzReference::gzReference()
//                                  
// Purpose  : Constructor
//                                  
// Params   : -         
//                                      
// Result   : -                 
//                                      
// Notes    : sets reference count to zero. Allows usage of class without references    
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created release 
//                                  
//******************************************************************************
inline gzReference::gzReference():_refCount(0),m_copyMode(GZ_CLONE_NO_SHARE)
{
}

//******************************************************************************
// Function : gzReference(gzReference &copy)
//                                  
// Purpose  : Copy Constructor
//                                  
// Params   : -         
//                                      
// Result   : -                 
//                                      
// Notes    : sets reference count to zero. Allows usage of class without references    
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created release 
//                                  
//******************************************************************************
inline gzReference::gzReference(const gzReference &copy):_refCount(0),m_copyMode(copy.m_copyMode)
{}

//******************************************************************************
// Function : gzReference & gzReference::operator=(const gzReference &copy)
//                                  
// Purpose  : Assignment operator
//                                  
// Params   : -         
//                                      
// Result   : -                 
//                                      
// Notes    : Do not change reference count. Allows usage of class without references   
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created release 
//                                  
//******************************************************************************
inline gzReference & gzReference::operator=(const gzReference &copy)
{
    m_copyMode=copy.m_copyMode;
    return *this;
}

//******************************************************************************
// Function : gzReference::~gzReference()
//                                  
// Purpose  : Destructor
//                                  
// Params   : -         
//                                      
// Result   : -                 
//                                      
// Notes    : if deleted when reference count !=0 exits software hard ! 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created release 
//                                  
//******************************************************************************
inline gzReference::~gzReference()
{
    if(_refCount)
    {
        throwFatalException("REFERENCE MISMATCH ! Deleted referenced object with nonzero reference count");
    }
}

//******************************************************************************
// Function : gzReference::clone()
//                                  
// Purpose  :   throws an exception if somebody tries to clone this object
//              User must provide an implementation if clone should be used !
//                                  
// Params   : -         
//                                      
// Result   : -                 
//                                      
// Notes    : -
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created release 
//                                  
//******************************************************************************
inline gzReference* gzReference::clone() const
{
    throwFatalException("Unimplemented clone called for type '%s'",(const char *)getTypeName());
    return NULL;
}

//******************************************************************************
// Function : gzReference::ref()
//                                  
// Purpose  : Increases reference count
//                                  
// Params   : -         
//                                      
// Result   : -
//                                      
// Notes    : - 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created release 
//                                  
//******************************************************************************
inline gzVoid gzReference::ref()
{
    ++_refCount;
}

//******************************************************************************
// Function : gzReference::checkDelete()
//                                  
// Purpose  : Checks if reference count is zero and deletes it if that is true
//                                  
// Params   : -         
//                                      
// Result   : gzBool - true if deleted          
//                                      
// Notes    : - 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created release 
//                                  
//******************************************************************************
inline gzBool gzReference::checkDelete()
{
    if(!_refCount)
    {
        delete this;
        return TRUE;
    }
    return FALSE;
}

//******************************************************************************
// Function : gzReference::unref()
//                                  
// Purpose  : Decrease reference count. If zero then deleted
//                                  
// Params   : -         
//                                      
// Result   : -         
//                                      
// Notes    : if unmatched references found then an exception is thrown 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created release 
//                                  
//******************************************************************************
inline gzVoid gzReference::unref()
{
    if(_refCount)
    {
        if(!(--_refCount))
            delete this;
    }
    else
    {
        throwFatalException("REFERENCE MISMATCH ! Unref an object with zero reference count.");
    }
}

//******************************************************************************
// Function : gzReference::unrefNoDelete()
//                                  
// Purpose  : Decrease reference count. 
//                                  
// Params   : -         
//                                      
// Result   : int - number of remaining references          
//                                      
// Notes    : if unmatched references exits software    
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  980819  Created release 
//                                  
//******************************************************************************
inline gzUInt gzReference::unrefNoDelete()
{
    if(_refCount)
    {
        --_refCount;
    }
    else
    {
        throwFatalException("REFRENCE MISMATCH ! Unref an object with zero reference count.");
    }
    return _refCount;
}

// ********** Referenced utility templates **************************************

//******************************************************************************
// Class    : gzRefPointer
//                                  
// Purpose  : Container with copy constructors etc. for referenced managed pointers
//                                  
// Notes    : - 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  981127  Created 
//                                  
//******************************************************************************
template <class T> class gzRefPointer
{
public:
    gzRefPointer();
    gzRefPointer( const gzRefPointer<T> &copy);
    gzRefPointer &operator=(const gzRefPointer<T> &copy);
    gzRefPointer( T *pointer);

    virtual ~gzRefPointer();

    gzVoid  set(T *pointer);

    T *     get()   const { return m_pointer; }

    operator T *()  const { return m_pointer; }

    T * operator ->()   const { return m_pointer;   }

    virtual gzVoid  setCopyMode(gzCopyMode mode)
    {
        if(m_pointer)
            m_pointer->setCopyMode(mode);
    }

private:
    T *m_pointer;
};

//******************************************************************************

template <class T> inline gzRefPointer<T>::gzRefPointer():m_pointer(NULL)
{
}

//******************************************************************************

template <class T> inline gzRefPointer<T>::gzRefPointer( const gzRefPointer<T> &copy)
{
    if(copy.m_pointer)
    {
        if(copy.m_pointer->useDeepCopy())
            m_pointer=(T *)copy.m_pointer->clone();
        else
            m_pointer=copy.m_pointer;
    }
    else
        m_pointer=NULL;

    if(m_pointer)
        m_pointer->ref();
}

//******************************************************************************

template <class T> inline gzRefPointer<T>::gzRefPointer( T *pointer)
{
    m_pointer=pointer;

    if(m_pointer)
        m_pointer->ref();
}


//******************************************************************************

template <class T> inline gzRefPointer<T> & gzRefPointer<T>::operator =(const gzRefPointer<T> &copy)
{
    if(copy.m_pointer==m_pointer)
        return *this;

    if(copy.m_pointer)
        copy.m_pointer->ref();

    if(m_pointer)
        m_pointer->unref();

    m_pointer=copy.m_pointer;
    
    return *this;
}

//******************************************************************************

template <class T> inline gzVoid gzRefPointer<T>::set(T *pointer)
{
    if(pointer==m_pointer)
        return;

    if(pointer)
        pointer->ref();

    if(m_pointer)
        m_pointer->unref();

    m_pointer=pointer;
}

//******************************************************************************

template <class T> inline gzRefPointer<T>::~gzRefPointer()
{
    if(m_pointer)
        m_pointer->unref();
}

#define GZ_DECLARE_REFPTR(x)    typedef gzRefPointer<x> x##Ptr

//******************************************************************************
// Class    : gzRefList
//                                  
// Purpose  : -
//                                  
// Notes    : - 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  981127  Created 
//                                  
//******************************************************************************
template <class T> class gzRefList : public gzList<T>
{
public:
    
    gzRefList(gzBool reuseLinks=FALSE):gzList<T>(reuseLinks),m_useDelayedRemove(FALSE){};

    // Special initializers

    gzRefList( const gzRefList<T> &copy ):m_useDelayedRemove(FALSE){ gzList<T>::operator=((const gzList<T> &)copy); }

    gzRefList<T> &operator=(const gzRefList<T> &copy ) { gzList<T>::operator=((const gzList<T> &)copy); return *this; }

    gzRefList( const gzList<T> &copy ):m_useDelayedRemove(FALSE){ operator=((const gzList<T> &)copy); }

    gzRefList<T> &operator=(const gzList<T> &copy ) 
    {
        if(&copy==this)
            return *this;

        clear();    // rensa gammal data

        typename gzList<T>::LinkItem *link=copy.m_link;

        gzList<T>::m_link=0;
        gzList<T>::m_last=0;

        while(link)
        {
            typename gzList<T>::LinkItem *newlink=gzList<T>::allocLink();

            newlink->item=link->item; // default share instance

            onInsert(newlink->item);

            newlink->sortval=link->sortval;

            newlink->next=0;

            if(gzList<T>::m_last)
                gzList<T>::m_last->next=newlink;
            else
                gzList<T>::m_link=newlink;

            gzList<T>::m_last=newlink;

            link=link->next;
        }
        gzList<T>::m_entries=copy.m_entries;

        return *this;
    }

    virtual ~gzRefList()
    { 
        clear(); 
    }

    gzVoid useDelayedRemove(gzBool on)
    {
        m_useDelayedRemove=on;
    }

    virtual gzVoid onInsert(T *item ) const 
    {
        if(item)
            item->ref();
    }

    virtual gzVoid onRemove(T *item ) const 
    {
        if(m_useDelayedRemove)
            ((gzRefList<T> *)this)->m_delayedRemove.set(item);

        if(item)
            item->unref();
    }

    virtual T *cloneEntry(T *item ) const 
    { 
        if(item)
        {
            if(item->useDeepCopy())
                return (T *)item->clone();
            else
                return item;
        }
        else
            return NULL;
    }
    virtual gzVoid  setCopyMode(gzCopyMode mode)
    {
        T *entry;
        
        gzListIterator<T> iterator(*this);
        
        while(entry=iterator())
        {
            entry->setCopyMode(mode);
        }
    }

    virtual gzVoid clear()
    {
        gzList<T>::clear();
        cleanDelayedRemove();
    }

    gzVoid cleanDelayedRemove()
    {
        m_delayedRemove=NULL;
    }


private:

    gzRefPointer<T> m_delayedRemove;

    gzBool          m_useDelayedRemove;

};

//******************************************************************************
// Class    : gzRefDList
//                                  
// Purpose  : -
//                                  
// Notes    : - 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  010222  Created 
//                                  
//******************************************************************************
template <class T> class gzRefDList : public gzDList<T>
{
public:
    
    gzRefDList():m_useDelayedRemove(FALSE){};
    gzRefDList( const gzRefDList &copy ):m_useDelayedRemove(FALSE){  gzDList<T>::operator=((const gzDList<T> &)copy); }
    gzRefDList( const gzRefList<T> &copy ):m_useDelayedRemove(FALSE){  gzDList<T>::operator=((const gzList<T> &)copy); }
    
    virtual ~gzRefDList()
    { 
        clear(); 
    }

    gzVoid useDelayedRemove(gzBool on)
    {
        m_useDelayedRemove=on;
    }
    
    virtual gzVoid onInsert(T *item ) const 
    {
        if(item)
            item->ref();
    }

    virtual gzVoid onRemove(T *item ) const
    {
        if(m_useDelayedRemove)
            ((gzRefDList<T> *)this)->m_delayedRemove.set(item);

        if(item)
            item->unref();
    }

    virtual T *cloneEntry(T *item ) const 
    { 
        if(item)
        {
            if(item->useDeepCopy())
                return (T *)item->clone();
            else
                return item;
        }
        else
            return NULL;
    }
    virtual gzVoid  setCopyMode(gzCopyMode mode)
    {
        T *entry;
        
        gzDListIterator<T> iterator(*this);
        
        while(entry=iterator())
        {
            entry->setCopyMode(mode);
        }
    }

    virtual gzVoid clear()
    {
        gzDList<T>::clear();
        cleanDelayedRemove();
    }

    gzVoid cleanDelayedRemove()
    {
        m_delayedRemove=NULL;
    }

private:

    gzRefPointer<T> m_delayedRemove;

    gzBool          m_useDelayedRemove;

};

//******************************************************************************
// Class    : gzRefDict
//                                  
// Purpose  : -
//                                  
// Notes    : - 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  981127  Created 
//                                  
//******************************************************************************
template <class T1 , class T2> class gzRefDict : public gzDict<T1,T2>
{
public:
    gzRefDict(unsigned long size=10,gzBool useAutoResize=FALSE):gzDict<T1,T2>(size,useAutoResize),m_useDelayedRemove(FALSE){};

    gzRefDict( const gzRefDict &copy ):gzDict<T1,T2>(0),m_useDelayedRemove(FALSE)   {  gzDict<T1,T2>::operator=((const gzDict<T1,T2> &)copy); }

    virtual ~gzRefDict() 
    { 
        clear(); 
    }

    gzVoid onInsert(const T1 & , T2 *item) const { if(item)item->ref();};

    gzVoid onRemove(const T1 & , T2 *item) const 
    { 
        if(m_useDelayedRemove)
            ((gzRefDict<T1,T2> *)this)->m_delayedRemove.set(item);

        if(item)item->unref();
    }

    virtual gzDictEntry<T1,T2> *cloneEntry( gzDictEntry<T1,T2> *item) const 
    {
        if(item)
        {
            if(item->getData()->useDeepCopy())
                return allocEntry(item->getKey(),(T2 *)item->getData()->clone(),item->getKey().hash());
            else
                return allocEntry(item->getKey(),item->getData(),item->getKey().hash()); 
        }
        else
            return NULL;
    }

    virtual gzVoid  setCopyMode(gzCopyMode mode)
    {
        gzDictEntry<T1,T2>      *entry;
        gzDictIterator<T1,T2>   iterator(*this);

        while(entry=iterator())
        {
            if(entry->getData())
                entry->getData()->setCopyMode(mode);
        }
    }

    gzVoid cleanDelayedRemove()
    {
        m_delayedRemove=NULL;
    }

    gzVoid useDelayedRemove(gzBool on)
    {
        m_useDelayedRemove=on;
    }

    virtual gzVoid clear()
    {
        gzDict<T1,T2>::clear();
        cleanDelayedRemove();
    }


private:

    gzRefPointer<T2>    m_delayedRemove;

    gzBool          m_useDelayedRemove;
};


//******************************************************************************
// Class    : gzRefData
//                                  
// Purpose  : -
//                                  
// Notes    : - 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  000101  Created 
//                                  
//******************************************************************************
template <class T1 , class T2=gzReference > class gzRefData : public T1 , public gzReference 
{
public:

    gzRefData(){};

    gzRefData( const T1 & copy ):T1(copy){};

    virtual ~gzRefData(){};

    virtual gzReference* clone() const 
    { 
        return new gzRefData<T1,T2>(*this); 
    }

    virtual gzVoid  setCopyMode(gzCopyMode mode)
    {
        gzReference::setCopyMode(mode);
    }

    static gzType *getClassType() { return T2::getClassType(); }

    virtual gzType *getType() const { return T2::getClassType(); }
};

//******************************************************************************

class gzRefInstanceDictionary : public gzRefDict<gzInstanceCompareInterface,gzReference> 
{
public:
    gzRefInstanceDictionary(gzULong size=100):gzRefDict<gzInstanceCompareInterface,gzReference>(size){};
};

class gzRefInstanceArray : public gzDynamicArray< gzRefPointer<gzReference> > 
{
public:
    gzRefInstanceArray(gzULong size=100) : gzDynamicArray< gzRefPointer<gzReference> >(size) {};
};

//******************************************************************************

//******************************************************************************
// Class    : gzRefIdStorage
//                                  
// Purpose  : Reference counted storage of UInt IDs
//                                  
// Notes    : - 
//                                  
// Revision History...                          
//                                  
// Who  Date    Description                     
//                                  
// AMO  030422  Created 
//                                  
//******************************************************************************
class gzRefIdStorage : public gzReference
{
public:

    gzQueue<gzUInt>     id;
};

#endif // __GZ_REFERENCE_H__

---