[Home]	[About]
[Screenshots]	[Download]
[News]	[Community]
[Documentation]	[Manual]
[Bugs & Requests]	[Wiki]

/home/tetron/hack/vos/libs/vos/vutil/refcount.hh

Go to the documentation of this file.

/*
    This file is part of the Virtual Object System of
    the Interreality project (http://interreality.org).

    Copyright (C) 2001-2003 Peter Amstutz

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser 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
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

    Peter Amstutz <http://www.interreality.org>
*/
#ifndef _VUTIL_REFCOUNT_HH_
#define _VUTIL_REFCOUNT_HH_

/** @file
    Defines and inline implements RefCount.
*/

#include <set>

#include <vos/vutil/vutildefs.hh>
#include <boost/thread/mutex.hpp>
#include <boost/thread/recursive_mutex.hpp>

namespace VUtil
{
#ifndef SWIG
class RefCounted;
#endif

/** @class ObjectExciseListener refcount.hh vos/vos/refcount.hh
    @ingroup libvutil

    Interface by which an application can be notified
    that an object wants to be excised.
*/
class VUTIL_API ObjectExciseListener
{
public:
    virtual ~ObjectExciseListener();

    /** This will be called by the listened-to object when its
        RefCounted::excise() method is called.  The application should take any
        appropriate measures to remove references (to avoid stale
        pointers and/or memory leaks) and then call release().
    */
    virtual void notifyObjectExcise(RefCounted* object) = 0;
};

/** @class RefCounted refcount.hh vos/vos/refcount.hh
    @ingroup libvutil

    This is a simple base class for reference counting
    objects.  It also provides a facility for tracking
    references to this object, so that they may be notified
    when the application wants this object to be deleted.
    You can use vRef to automatically release RefCounted objects
    when they would normally be destroyed (go out of scope).

    @note If you have a situation where you are doing multiple
    inheritance from two or more classes that (directly or indirectly)
    themselves inherit from RefCounted, you need to mark your
    inheritance as a virtual base class.  This means in your code
    @code
    class Foo : public virtual RefCounted { ... };
    class Bar : public virtual RefCounted { ... };
    class Baz : public virtual Foo, public virtual Bar { ... };
    @endcode
    Otherwise you could have two (or more) seperate
    reference counters for the same object, and that won't do at all.
*/
#if !defined(SWIG)
class VUTIL_API RefCounted
{
private:
    int count;
    boost::mutex count_mutex;

    std::set<ObjectExciseListener*>* exciseListeners;
    boost::recursive_mutex exciseListeners_mutex;
public:
    /** Construct the refcount object with a starting count of 1 */
    RefCounted() : count(1), exciseListeners(0) { };

    /** copy constructor, need to reset count on the copy */
    RefCounted(const RefCounted& /*rc*/) : count(1), exciseListeners(0) { };

    /** Destructor. (Cleans up excise listeners) */
    virtual ~RefCounted() { if(exciseListeners) delete exciseListeners; }

    /** This method is used by release() to destroy this object if the
        refcount reaches 0.  By default, it simply calls "delete
        this".  However, you can override it in a subclass if you
        really want to do something other than deleting this object.
    */
    virtual void destroy();

    /** Increment the reference count. */
    virtual void acquire();

    /** Decrement the reference count.  The object will be deleted if (count == 0) */
    virtual void release();

    /** Get the current reference count */
    virtual int getRefCount();

    /** Add an excise listener.  When the excise() method is called on
        this object, each excise listener will be notified so that it
        may clean up any references to this object.

        @param oel the excise listener to call back.  This can itself
        be a refcounted object, and if so, its refcount will be incremented.
    */
    virtual void addExciseListener(ObjectExciseListener* oel);

    /** Remove an excise listener.
        @see addExciseListener()
        @param oel the ObjectExciseListener to remove
        @param releaseIfRefcounted Should we test the object excise
        listener to see if it is refcounted, and if so release it?
        Under certain special circumstances (such as calling
        "removeExciseListener(this)" from a destructor) this behavior
        is undesirable.
    */
    virtual void removeExciseListener(ObjectExciseListener* oel,
                                      bool releaseIfRefcounted = true);

    /** Ask that all known references to this object to release
        their references so the object can be deleted, by calling
        ObjectExciseListener::notifyObjectExcise().

        @note This method is virtual and objects making use of this
        class will probably want to supply their own additional code
        to detach from linking data structures.  Make sure to call
        RefCounted::excise() in yoru override method so that the
        excise listeners are called back.  Overriding excise() will
        probably be sufficient for most uses; the purpose of the
        ObjectExciseListener facility is for plugin/application level
        hooks which may be beyond the scope of your immediate code.
     */
    virtual void excise();
};
#endif

/** @class NullPointerError refcount.hh vos/vos/refcount.hh
    @ingroup libvutil

    This is raised if you try and dereference a vRef which contains a
    null pointer.
 */
class VUTIL_API NullPointerError : public std::runtime_error {
public:
    NullPointerError(const std::string& s) : runtime_error(s) { };
};


/** @class vRef refcount.hh vos/vos/refcount.hh
    @ingroup libvutil

   This is a "smart pointer" wrapper class around any RefCounted
   object. When you assign a pointer to a vRef, it calls aquire(),
   increasing the refcount on that object.  When vRef goes out of
   scope (i.e., when it is destroyed) it automatically calls release
   on the wrapped object.  For more discussion and examples, see the
   VOS manual and the tutorial programs (in "apps/tutorials").

   @note vRef is not threadsafe. You must not share the same vRef
   instance between threads -- copy it instead!
 */

template<class T> class vRef
{
private:
    T* ptr;

public:
    /** Initialize an empty vRef that points to nothing. */
    vRef() : ptr(0) { }

    /** @param x Pointer to object to wrap in this vRef: it must be a RefCounted
            class or subclass.
        @param doacquire If true, object will be acquired and reference count
            will be incremented. If false, the object will retain it's current
            reference count.  Note that when a RefCounted object is created with
            "new" its reference count is already 1, and in this case you shouldn't
            increment the count.
    */
    vRef(T* x, bool doacquire) : ptr(x) { if(ptr && doacquire) ptr->acquire(); }

    /** @param x Reference to object to wrap in this vRef: it must be a
            RefCounted class or subclass.
        @param doacquire If true, object will be acquired and reference count
            will be incremented. If false, the object will retain it's current
            reference count.  Note that when a RefCounted object is created with
            "new" its reference count is already 1, and in this case you shouldn't
            increment the count.

    */
    vRef(T& x, bool doacquire) : ptr(&x) { if(ptr && doacquire) ptr->acquire(); }

    /** Create a new vRef containing the same object as another vRef. The
            reference count of the object will be incremented.
        @param x vRef to copy.
    */
    vRef(const vRef<T>& x) : ptr(x.ptr) { if(ptr) ptr->acquire(); }

    /** Create a new vRef containing the same object as another vRef. The
            reference count of the object will be incremented. This form
            allows the other vRef to use a different class in its template.
        @param x vRef to copy.
    */
    template<class T2> vRef(const vRef<T2>& x) {
        if(x.isValid()) {
            ptr = x.get();
            ptr->acquire();
        } else ptr = 0;
    }

    /** Destructor.  Decrements the reference count on the underlying
        pointer. */
    ~vRef() { if(ptr) ptr->release(); }

    /** Test whether this vRef holds a valid pointer or not.
        @return true if internal pointer is not null (0), false if
        internal pointer is null (0).
    */
    bool isValid() const { return (ptr != 0); }

#ifndef SWIG
    /** @return true if the wrapped pointer is null, false if it is
        valid */
    bool operator!() const { return (ptr == 0); }

    bool operator==(const vRef& x) const { return (x.ptr == ptr); }
    bool operator!=(const vRef& x) const { return (x.ptr != ptr); }

    bool operator==(const T* x) const { return (x == ptr); }
    bool operator!=(const T* x) const { return (x != ptr); }

    bool operator==(const T& x) const { return ( (ptr != 0) && (x == *ptr) ); }
    bool operator!=(const T& x) const { return ( (ptr != 0) && (x != *ptr) ); }

    /** Assign a new object to this vRef. If this vRef is holding an object,
        that object will be released (it's reference count decremented).
        @param x the new pointer
        @param doacquire If true, object will be acquired and
        reference count will be incremented. If false, the object will
        retain it's current reference count.  When a new RefCounted
        object is created (e.g. with "new"), its reference count is
        already 1, and you don't need to increment the count.
    */
    template<class T2> vRef<T>& assign(T2* x, bool doacquire) {
        if(ptr) ptr->release();
        ptr = x;
        if(ptr && doacquire) ptr->acquire();
        return *this;
    }

    /** Assign to another vRef. Old wrapped object is released, and new
        wrapped object is acquired. */
    vRef<T>& operator=(const vRef<T>& x) {
        if(ptr) ptr->release();
        ptr = x.ptr;
        if(ptr) ptr->acquire();
        return *this;
    }

    /** Assign to another vRef. Old wrapped object is released, and new
        wrapped object is acquired. */
    template<class T2> vRef<T>& operator=(const vRef<T2>& x) {
        if(ptr) ptr->release();
        if(x.isValid()) {
            ptr = x.get();
            if(ptr) ptr->acquire();
        }
        return *this;
    }

    /** Return reference to wrapped object.
        @throw NullPointerError if internal pointer is 0 (no object held)
    */
    T& operator*() const {
        if(ptr) return *ptr;
        else throw NullPointerError("tried to dereference null smart pointer in * operator");
    }
#endif

    /** Return pointer to wrapped object.
        @throw NullPointerError if internal pointer is 0 (no object held)
    */
    T* operator->() const {
        if(ptr) return ptr;
        else throw NullPointerError("tried to dereference null smart pointer in -> operator");
    }

    /** Return pointer to wrapped object
        @throw NullPointerError if internal pointer is 0 (no object held)
    */
    T* get() const {
        if(ptr) return ptr;
        else throw NullPointerError("tried to dereference null smart pointer in & operator");
    }

    /** Release object and set internal pointer to 0. */
    void clear() {
        if(ptr) ptr->release();
        ptr = 0;
    }


#ifndef SWIG

    /** Cast to pointer.  Same as get().
            Usually used by implicit cast in a function call.
        @throw NullPointerError if internal pointer is 0 (no object held)
    */
    operator T*() {
        if(ptr) return ptr;
        else throw NullPointerError("tried to dereference null smart pointer in cast");
    }

    /** Cast to reference. Same as the operator*().
            Usually used by implicit cast in a function call.
        @throw NullPointerError if internal pointer is 0 (no object is held)
    */
    operator T&() {
        if(ptr) return *ptr;
        else throw NullPointerError("tried to dereference null smart pointer in cast to reference");
    }

#endif // ifndef SWIG

};

}

#endif