ref.H

/*
 * This file is part of the "Archon" framework.
 * (http://files3d.sourceforge.net)
 *
 * Copyright © 2002 by Kristian Spangsege and Brian Kristiansen.
 *
 * Permission to use, copy, modify, and distribute this software and
 * its documentation under the terms of the GNU General Public License is
 * hereby granted. No representations are made about the suitability of
 * this software for any purpose. It is provided "as is" without express
 * or implied warranty. See the GNU General Public License
 * (http://www.gnu.org/copyleft/gpl.html) for more details.
 *
 * The characters in this file are ISO8859-1 encoded.
 *
 * The documentation in this file is in "Doxygen" style
 * (http://www.doxygen.org).
 */

#ifndef ARCHON_UTILITIES_REF_H
#define ARCHON_UTILITIES_REF_H

#include <string>
#include <vector>
#include <algorithm>

#include <archon/util/exception.H>
#include <archon/util/mutex.H>

#include <archon/util/cxx_demangle.H>

namespace Archon
{
  namespace Utilities
  {
    using namespace std;

    template<typename T> struct BackRef;
    struct RefMapBase;
    template<typename T> struct RefMap;
    struct Thread;

    struct ForwardDestroyedException: Exception
    {
      ForwardDestroyedException(string l): Exception(l) {}
    };


    struct RefNoLockTag {};

    struct RefSafeIncTag {};


    template<typename T>
    struct Ref
    {
      typedef T ObjectType;

      Ref(): p(0) {}

      Ref(T *p): p(p) { inc(); }

      Ref(const Ref &r): p(r.p) { inc(); }
      template<typename U> Ref(const Ref<U> &r): p(r.p) { inc(); }

      ~Ref() { dec(); }

      void reset(T *p=0);

      void swap(Ref &r) { std::swap(p, r.p); }

      Ref &operator=(const Ref &);
      template<typename U> Ref &operator=(const Ref<U> &);

      template<typename U> bool operator==(const Ref<U> &) const;
      template<typename U> bool operator!=(const Ref<U> &) const;
      template<typename U> bool operator<(const Ref<U> &) const;
      template<typename U> bool operator>(const Ref<U> &) const;

      T *operator->() const;

      operator bool() const { return p; }

      T *get() const { return p; }

      bool sole() const { return p && p->refSole(); }


      Ref(T *p, RefNoLockTag): p(p) { incNoLock(); }


      Ref(T *p, RefSafeIncTag);

    private:
      template<typename U> friend struct Ref;
      friend struct BackRef<T>;
      friend struct RefMap<T>;

      T *p;

      void inc() const { if(p) p->refInc(); }
      void dec() const { if(p) p->refDec(); }

      void incNoLock() const { if(p) p->refIncNoLock(); }
    };



    struct RefObjectBase: protected virtual Mutex
    {
      virtual ~RefObjectBase() {}

      unsigned long getUseCount() const;

    protected:
      RefObjectBase(): useCount(0) {}

      virtual void refDispose(Mutex::Lock &);

      unsigned long getUseCountNoLock() const { return useCount; }

    private:
      template<typename T> friend struct Ref;
      template<typename T> friend struct BackRef;
      friend struct BackRefObjectBase;
      friend struct RefMapBase;
      friend struct Thread;

      void refInc() const;
      void refDec() const;

      void refIncNoLock() const;

      virtual bool refTryInc() const;

      bool refSole() const;

      mutable unsigned long useCount;
    };


    typedef Ref<RefObjectBase> RefAny;
    typedef Ref<const RefObjectBase> RefAnyConst;


    template<typename T>
    struct RefObject: virtual RefObjectBase
    {
      T value;
      RefObject(T v): value(v) {}
    };




    template<typename T>
    struct BackRef
    {
      typedef T ObjectType;

      BackRef(): p(0) {}

      BackRef(const Ref<T> &r): p(r.get()) { inc(); }
      BackRef(const BackRef &r): p(r.p) { inc(); }
      template<typename U> BackRef(const BackRef<U> &r): p(r.p) { inc(); }

     ~BackRef() { dec(); }

      void reset() { reset(0); }

      void reset(const Ref<T> &r) { reset(r.p); }

      void swap(BackRef &r) { std::swap(p, r.p); }

      BackRef &operator=(const BackRef &);
      template<typename U> BackRef &operator=(const BackRef<U> &);

      template<typename U> bool operator==(const BackRef<U> &) const;
      template<typename U> bool operator!=(const BackRef<U> &) const;

      template<typename U> bool operator==(const Ref<U> &) const;
      template<typename U> bool operator!=(const Ref<U> &) const;

      template<typename U> bool operator==(const U *) const;
      template<typename U> bool operator!=(const U *) const;

      Ref<T> operator->() const throw(ForwardDestroyedException);

      operator bool() const { return p; }

      Ref<T> getRef() const throw(ForwardDestroyedException);

    private:
      template<typename U> friend struct BackRef;

      T *p;

      void reset(T *p);

      void inc() const { if(p) p->backRefInc(); }
      void dec() const { if(p) p->backRefDec(); }
    };


    struct BackRefObjectBase: virtual RefObjectBase
    {
      unsigned long getBackUseCount() const;

    protected:
      BackRefObjectBase(): backUseCount(0), forwardDestroyed(false) {}

      virtual void refDispose(Mutex::Lock &);

      virtual void refForwardDestroy() = 0;

      unsigned long getBackUseCountNoLock() const { return backUseCount; }

    private:
      template<typename T> friend struct Ref;
      template<typename T> friend struct BackRef;

      void backRefInc() const;
      void backRefDec() const;

      virtual bool refTryInc() const;

      mutable unsigned long backUseCount;
      bool forwardDestroyed;
    };





    struct RefMapBase
    {
    protected:
      unsigned long get(RefObjectBase *, bool create);

      RefObjectBase *getNoLock(unsigned long key) const
      {
        return key < refs.size() ? refs[key].first : 0;
      }

      void remove(unsigned long key, unsigned long transCount)
      {
        if(!key) return;
        Mutex::Lock l(refMapMutex);
        if(key >= refs.size()) return;
        removeNoLock(refs[key].first, transCount);
      }

      void remove(RefObjectBase *r)
      {
        Mutex::Lock l(refMapMutex);
        removeNoLock(r, 0);
      }

      void clearNoLock(bool destroyRefs);

      Mutex refMapMutex;
      // Pairs of refs and translation count
      vector<pair<RefObjectBase *, unsigned long> > refs;

      unsigned long size()
      {
        Mutex::Lock l(refMapMutex);
        return refs.size() - unused.size() - 1;
      }

      string disp();

      RefMapBase();
      ~RefMapBase();

    private:
      static const unsigned long hashSize = 127;

      vector<unsigned long> *chunks[hashSize];
      vector<unsigned long> unused;

      void removeNoLock(RefObjectBase *, unsigned long transCount);
    };

    template<typename T>
    struct RefMap: private RefMapBase
    {
      RefMapBase::size;

      RefMapBase::disp;

      unsigned long get(Ref<T> r, bool create=true)
      {
        return RefMapBase::get(const_cast<RefObjectBase *>
                               (static_cast<const RefObjectBase *>
                                (r.get())), create);
      }

      Ref<T> operator()(unsigned long key) const
      {
        Mutex::Lock l(refMapMutex);
        return dynamic_cast<T *>(getNoLock(key));
      }

      void remove(unsigned long key, unsigned long transCount=0)
      {
        RefMapBase::remove(key, transCount);
      }

      void remove(Ref<T> r)
      {
        RefMapBase::remove(const_cast<RefObjectBase *>
                           (static_cast<const RefObjectBase *>(r.get())));
      }

      void clear(vector<Ref<T> > *remains = 0)
      {
        if(remains)
        {
          remains->clear();
          remains->resize(size());
          Mutex::Lock l(refMapMutex);
          unsigned j = 0;
          for(unsigned i = 1; i<refs.size(); ++i)
          {
            RefObjectBase *r = refs[i].first;
            if(r) remains->operator[](j++).p = dynamic_cast<T *>(r);
          }
          RefMapBase::clearNoLock(false);
        }
        else
        {
          Mutex::Lock l(refMapMutex);
          RefMapBase::clearNoLock(true);
        }
      }
    };





    template<typename T>
    inline void Ref<T>::reset(T *_p)
    {
      if(p == _p) return;
      dec();
      p = _p;
      inc();
    }

    template<typename T>
    inline Ref<T> &Ref<T>::operator=(const Ref &r)
    {
      reset(r.p);
      return *this;
    }

    template<typename T> template<typename U>
    inline Ref<T> &Ref<T>::operator=(const Ref<U> &r)
    {
      reset(r.p);
      return *this;
    }

    template<typename T> template<typename U>
    inline bool Ref<T>::operator==(const Ref<U> &r) const
    {
      return p == r.p;
    }

    template<typename T> template<typename U>
    inline bool Ref<T>::operator!=(const Ref<U> &r) const
    {
      return p != r.p;
    }

    template<typename T> template<typename U>
    inline bool Ref<T>::operator<(const Ref<U> &r) const
    {
      return p < r.p;
    }

    template<typename T> template<typename U>
    inline bool Ref<T>::operator>(const Ref<U> &r) const
    {
      return p > r.p;
    }

    template<typename T>
    inline T *Ref<T>::operator->() const
    {
      if(p) return p;
      ARCHON_THROW1(StateException, "Dereferencing null");
    }

    template<typename T>
    inline Ref<T>::Ref(T *_p, RefSafeIncTag): p(0)
    {
      if(_p && _p->refTryInc()) p = _p;
    }



    inline void RefObjectBase::refInc() const
    {
      Mutex::Lock l(*this);
      ++useCount;
    }

    inline void RefObjectBase::refDec() const
    {
      Mutex::Lock l(*this);
      if(!--useCount) const_cast<RefObjectBase *>(this)->refDispose(l);
    }

    inline void RefObjectBase::refIncNoLock() const
    {
      ++useCount;
    }

    inline void RefObjectBase::refDispose(Mutex::Lock &l)
    {
      l.release();
      // Note: The validity of this self destruction relies on the
      // fact that no explicit or implict references to "this" are
      // made after the delete statement (keep it like that).
      delete this;
    }

    inline bool RefObjectBase::refTryInc() const
    {
      Mutex::Lock l(*this);
      if(useCount)
      {
        ++useCount;
        return true;
      }
      return false;
    }

    inline bool RefObjectBase::refSole() const
    {
      Mutex::Lock l(*this);
      return useCount == 1;
    }

    inline unsigned long RefObjectBase::getUseCount() const
    {
      Mutex::Lock l(*this);
      return useCount;
    }




    template<typename T>
    inline void BackRef<T>::reset(T *_p)
    {
      if(p == _p) return;
      dec();
      p = _p;
      inc();
    }

    template<typename T>
    inline BackRef<T> &BackRef<T>::operator=(const BackRef &r)
    {
      reset(r.p);
      return *this;
    }

    template<typename T> template<typename U>
    inline BackRef<T> &BackRef<T>::operator=(const BackRef<U> &r)
    {
      reset(r.p);
      return *this;
    }

    template<typename T> template<typename U>
    inline bool BackRef<T>::operator==(const BackRef<U> &r) const
    {
      return p == r.p;
    }

    template<typename T> template<typename U>
    inline bool BackRef<T>::operator!=(const BackRef<U> &r) const
    {
      return p != r.p;
    }

    template<typename T> template<typename U>
    inline bool BackRef<T>::operator==(const Ref<U> &r) const
    {
      return p == r.get();
    }

    template<typename T> template<typename U>
    inline bool BackRef<T>::operator!=(const Ref<U> &r) const
    {
      return p != r.get();
    }

    template<typename T> template<typename U>
    inline bool BackRef<T>::operator==(const U *r) const
    {
      return p == r;
    }

    template<typename T> template<typename U>
    inline bool BackRef<T>::operator!=(const U *r) const
    {
      return p != r;
    }

    template<typename T>
    inline Ref<T> BackRef<T>::getRef() const throw(ForwardDestroyedException)
    {
      if(!p) return 0;
      Ref<T> r(p, RefSafeIncTag());
      if(!r) ARCHON_THROW(ForwardDestroyedException);
      return r;
    }

    template<typename T>
    inline Ref<T> BackRef<T>::operator->() const
      throw(ForwardDestroyedException)
    {
      if(!p) return 0;
      Ref<T> r(p, RefSafeIncTag());
      if(!r) ARCHON_THROW(ForwardDestroyedException);
      return r;
    }




    inline void BackRefObjectBase::backRefInc() const
    {
      Mutex::Lock l(*this);
      ++backUseCount;
    }

    inline void BackRefObjectBase::backRefDec() const
    {
      Mutex::Lock l(*this);
      if(!--backUseCount) const_cast<BackRefObjectBase *>(this)->refDispose(l);
    }


    inline bool BackRefObjectBase::refTryInc() const
    {
      Mutex::Lock l(*this);
      if(useCount&&!forwardDestroyed)
      {
        ++useCount;
        return true;
      }
      return false;
    }


    inline void BackRefObjectBase::refDispose(Mutex::Lock &l)
    {
      if(!useCount)
      {
        if(!backUseCount)
        {
          l.release();

          // Note: The validity of this self destruction relies on the
          // fact that no explicit or implict references to "this" are
          // made after the delete statement (keep it like that).
          delete this;
          return;
        }

        if(forwardDestroyed) return;
        forwardDestroyed = true;
        Ref<BackRefObjectBase> r(this, RefNoLockTag());
        l.release();
        r->refForwardDestroy();
      }
    }

    inline unsigned long BackRefObjectBase::getBackUseCount() const
    {
      Mutex::Lock l(*this);
      return backUseCount;
    }
  }
}

namespace std
{
  template<typename T>
  void swap(Archon::Utilities::Ref<T> &r,
            Archon::Utilities::Ref<T> &s)
  {
    r.swap(s);
  }

  template<typename T>
  void swap(Archon::Utilities::BackRef<T> &r,
            Archon::Utilities::BackRef<T> &s)
  {
    r.swap(s);
  }
}

#endif // ARCHON_UTILITIES_REF_H

---