Public API Reference

csutil/ref.h

Go to the documentation of this file.

/*
  Crystal Space Smart Pointers
  Copyright (C) 2002 by Jorrit Tyberghein and Matthias Braun

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Library General Public
  License as published by the Free Software Foundation; either
  version 2 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Library General Public License for more details.

  You should have received a copy of the GNU Library General Public
  License along with this library; if not, write to the Free
  Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/

#ifndef __CS_REF_H__
#define __CS_REF_H__

#include "csextern.h"

#include "csutil/customallocated.h"
#include "csutil/threading/atomicops.h"

#define CS_VOIDED_PTR ((intptr_t)-1)

template <class T> class csRef;

#if defined(CS_DEBUG)
#  define CS_TEST_VOIDPTRUSAGE
#else
#  undef CS_TEST_VOIDPTRUSAGE
#endif

#ifdef CS_REF_TRACKER
 #include <typeinfo>
 #include "csutil/reftrackeraccess.h"

 #define CSREF_TRACK(x, cmd, refCount, obj, tag)    \
  {                                                 \
    const int rc = obj ? refCount : -1;             \
    if (obj)                                        \
    {                                               \
      cmd;                                          \
      csRefTrackerAccess::SetDescriptionWeak (obj,  \
        typeid(T).name());                          \
      csRefTrackerAccess::Match ## x (obj, rc, tag);\
    }                                               \
  }
 #define CSREF_TRACK_INCREF(obj,tag)    \
  CSREF_TRACK(IncRef, obj->IncRef(), obj->GetRefCount(), obj, tag);
 #define CSREF_TRACK_DECREF(obj,tag)    \
  CSREF_TRACK(DecRef, obj->DecRef(), obj->GetRefCount(), obj, tag);
 #define CSREF_TRACK_ASSIGN(obj,tag)    \
  CSREF_TRACK(IncRef, void(0), obj->GetRefCount() - 1, obj, tag);
#else
 #define CSREF_TRACK_INCREF(obj,tag) \
  if (obj) obj->IncRef();
 #define CSREF_TRACK_DECREF(obj,tag) \
  if (obj) obj->DecRef();
 #define CSREF_TRACK_ASSIGN(obj,tag)
#endif

template <class T>
class csPtr : public CS::Memory::CustomAllocated
{
private:
  friend class csRef<T>;
  T* obj;

public:
  csPtr (T* p) : obj (p) { CSREF_TRACK_ASSIGN(obj, this); }

  template <class T2>
  csPtr (csRef<T2> const& r) : obj((T2*)r)
  { 
    CSREF_TRACK_INCREF (obj, this);
  }

#ifdef CS_TEST_VOIDPTRUSAGE
  ~csPtr ()
  {
    // If not assigned to a csRef we have a problem (leak).
    // So if this assert fires for you, then you are calling
    // a function that returns a csPtr and not using the result
    // (or at least not assigning it to a csRef). This is a memory
    // leak and you should fix that.
    CS_ASSERT_MSG ("csPtr<> was not assigned to a csRef<> prior destruction", 
      obj == (T*)CS_VOIDED_PTR);
  }
#endif

  csPtr (const csPtr<T>& copy)
  {
    obj = copy.obj;
#ifdef CS_TEST_VOIDPTRUSAGE
    ((csPtr<T>&)copy).obj = (T*)CS_VOIDED_PTR;
#endif
  }
};

template <class T>
class csRef : public CS::Memory::CustomAllocated
{
private:
  T* obj;

public:
  csRef () : obj (0) {}

  csRef (const csPtr<T>& newobj)
  {
    obj = newobj.obj;
#   ifdef CS_TEST_VOIDPTRUSAGE
    CS_ASSERT_MSG ("csPtr<> was already assigned to a csRef<>",
      newobj.obj != (T*)CS_VOIDED_PTR);
#   endif
    // The following line is outside the ifdef to make sure
    // we have binary compatibility.
    ((csPtr<T>&)newobj).obj = (T*)CS_VOIDED_PTR;
  }

  csRef (T* newobj) : obj (newobj)
  {
    CSREF_TRACK_INCREF (obj, this);
  }

  template <class T2>
  csRef (T2* newobj) : obj ((T2*)newobj)
  {
    CSREF_TRACK_INCREF (obj, this);
  }
  
  template <class T2>
  csRef (csRef<T2> const& other) : obj ((T2*)other)
  {
    CSREF_TRACK_INCREF (obj, this);
  }

  csRef (csRef const& other) : obj (other.obj)
  {
    CSREF_TRACK_INCREF (obj, this);
  }

  ~csRef ()
  {
    CSREF_TRACK_DECREF (obj, this);
  }

  csRef& operator = (const csPtr<T>& newobj)
  {
#   ifdef CS_TEST_VOIDPTRUSAGE
    CS_ASSERT_MSG ("csPtr<> was already assigned to a csRef<>",
      newobj.obj != (T*)CS_VOIDED_PTR);
#   endif
    T* oldobj = (T*)CS::Threading::AtomicOperations::Read ((void**)&obj);
    // First assign and then DecRef() of old object!
    if (CS::Threading::AtomicOperations::CompareAndSet ((void**)&obj,
      newobj.obj, oldobj) == oldobj)
    {
      CSREF_TRACK_DECREF (oldobj, this);
    }
    else
    {
      /* Assign was not successful. But to pretend we have taken ownership,
       * DecRef() new object */
      CSREF_TRACK_DECREF (newobj.obj, this);
    }
    // The following line is outside the ifdef to make sure
    // we have binary compatibility.
    ((csPtr<T>&)newobj).obj = (T*)CS_VOIDED_PTR;
    return *this;
  }

  csRef& operator = (T* newobj)
  {
    T* oldobj = (T*)CS::Threading::AtomicOperations::Read ((void**)&obj);
    if (oldobj != newobj)
    {
      // It is very important to first assign the new value to
      // 'obj' BEFORE calling DecRef() on the old object. Otherwise
      // it is easy to get in infinite loops with objects being
      // destructed forever (when ref=0 is used for example).
      if (CS::Threading::AtomicOperations::CompareAndSet ((void**)&obj,
        newobj, oldobj) == oldobj)
      {
        CSREF_TRACK_INCREF (newobj, this);
        CSREF_TRACK_DECREF (oldobj, this);
      }
    }
    return *this;
  }

  void AttachNew (csPtr<T> newObj)
  {
    // Note: The parameter usage of csPtr<T> instead of csPtr<T>& is
    // deliberate and not to be considered a bug.

    // Just Re-use csPtr assignment logic
    *this = newObj;
  }

  template <class T2>
  csRef& operator = (csRef<T2> const& other)
  {
    T* p = (T2*)other;
    this->operator=(p);
    return *this;
  }

  csRef& operator = (csRef const& other)
  {
    this->operator=(other.obj);
    return *this;
  }

  inline friend bool operator == (const csRef& r1, const csRef& r2)
  {
    return r1.obj == r2.obj;
  }
  inline friend bool operator != (const csRef& r1, const csRef& r2)
  {
    return r1.obj != r2.obj;
  }
  inline friend bool operator == (const csRef& r1, T* obj)
  {
    return r1.obj == obj;
  }
  inline friend bool operator != (const csRef& r1, T* obj)
  {
    return r1.obj != obj;
  }
  inline friend bool operator == (T* obj, const csRef& r1)
  {
    return r1.obj == obj;
  }
  inline friend bool operator != (T* obj, const csRef& r1)
  {
    return r1.obj != obj;
  }
  inline friend bool operator < (const csRef& r1, const csRef& r2)
  {
    return r1.obj < r2.obj;
  }


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

  bool IsValid () const
  { return (obj != 0); }

  void Invalidate()
  { *this = (T*)0; }

  uint GetHash() const
  { return (uintptr_t)obj;  }
};

#undef CSREF_TRACK_INCREF
#undef CSREF_TRACK_DECREF
#undef CSREF_TRACK_ASSIGN

#endif // __CS_REF_H__

---