vos/corelibs/vos/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 <tetron@interreality.org>
*/
#ifndef _REFCOUNT_HH_
#define _REFCOUNT_HH_

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

#include <vos/corelibs/vos/vosdefs.hh>

#include <set>

/** @def pREF(type, ptr, value, body)
    @deprecated Use vRef
    @param type the pointer type (Foo*) of the referred-to object
    @param ptr the variable that will be used in this lexical block
    @param value the value assigned to the named variable, this should be is where refcounted object is acquired
    @param body relevant code that operates on the variable

    Please note that pREF and rREF have been deprecated in favor of
    the vRef smart pointer template!  However they still show up from
    time to time in the code...

    This macro defines a lexical scope in which you have a reference
    to a reference-counted object.  The purpose of this macro is to
    simplify tracking the acquire/release pair in the most common case
    of accessing a refcounted object by calling release() for you when
    you're clearly done accessing the refcounted object.
    This example should make it clearer:
    @code
    pREF(Sphere*, sphere, MetaObject::meta_cast<Sphere*>(MetaFactory::createLocalObject(&ls, typeid(Sphere).name(), 0));,
         sphere->setAccessControl(&NoPropertyAccessControl::static_NoPropertyAccessControl);
         sphere->setMaterial("#FF0000");
         // more sphere->setSomething(); method calls
         model->insertChild(-1, "ball", sphere);
        );
    @endcode
    This macro evaluates to the following (edited for readability):
    @code
    {
        Sphere* sphere = MetaObject::meta_cast<Sphere*>(MetaFactory::createLocalObject(&ls, typeid(Sphere).name(), 0));
        try {
            sphere->setAccessControl(&NoPropertyAccessControl::static_NoPropertyAccessControl);
            sphere->setMaterial("#FF0000");
            // more sphere->setSomething(); method calls
            model->insertChild(-1, "ball", sphere);
            if(sphere) sphere->release();
        } catch(exception x) {
            if(sphere) sphere->release();
            throw;
        }
    }
    @endcode
    @note In this example, a new sphere object is allocated, it's
    state is set, and then it is (implicitly) released.  Because the
    object has been inserted into another Vobject ("model") it will
    not be deleted.  If it had not been acquired by another section of
    the program, closing this block (calling release()) would cause
    "sphere" to be deleted.  Also note that acquire() should be called
    by the function RETURNING the value, so if you receive a
    refcounted object you should assume that the count has already
    been incremented.  Note that if you do get a NULL assigned to your
    variable, it will detect that and not try to release, so you can
    use these macros with methods that may return '0' on error.  You
    are only responsible for calling release() when you are done if
    you are not using this macro.  Exceptions which inherit from the
    base class 'exception' will be caught, the refcount released
    appropriately, and re-thrown.  If you 'return', 'continue',
    'break', 'goto' or otherwise jump to another part of your program
    while in one of these macro blocks, release() WILL NOT get called.
    Finally, if you get an error that looks like "macro `pREF' used
    with too many (#) args", this means the compiler has probably
    gotten confused on a statement like this:
@code
    int foo, bar, baz;
@endcode
    If this is the case, to un-confuse the compiler you need to
    seperate out each variable declaration.
@code
    int foo;
    int bar;
    int baz;
@endcode
*/

/** @def rREF(type, ptr, value, body)
    Like pREF, only the value is a C++ reference (Foo&) instead of a pointer (Foo*).
 */

#define rREF(type, ptr, value, body) { type ptr = value; \
                                       try { body; (ptr).release(); \
                                       } catch(...) { (ptr).release(); throw; } }
#define pREF(type, ptr, value, body) { type ptr = value; \
                                       try { body; if(ptr) (ptr)->release(); \
                                       } catch(...) { if(ptr) (ptr)->release(); throw; } }
namespace VOS
{
class RefCounted;

/** @class ObjectExciseListener refcount.hh vos/corelibs/vos/refcount.hh
 *
 * Interface by which an application can be notified
 *  that an object wants to be excised.
*/
class VOS_API ObjectExciseListener
{
public:
    /** 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/corelibs/vos/refcount.hh
 *
 * 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 When you inherit from this make sure you inherit it as a
    @em virtual base class.  That means
    @code
    class Foo : public virtual RefCounted { ... };
    @endcode
    Otherwise you could have two (or more) seperate
    reference counters for the same object, and that won't do at all.
*/
class VOS_API RefCounted
{
private:
    int count;
    set<ObjectExciseListener*>* exciseListeners;
public:
    /** Construct the refcount object with a starting count of 1 */
    RefCounted() : count(1), exciseListeners(0) { };

    /** copy constructor, need to reset count for 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 need 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 getCount();

    /** 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.
    */
    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);

    /** Try to cause all known references to this object to release
        their references so the object will 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 code to detach
        from linking data structures.  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();
};

/** @class vRef refcounted.hh vos/corelibs/vos/refcounted.hh
 *
 *  This is a "smart pointer" wrapper class around any RefCounted object. vRef
 *  automatically releases its contained object when it goes out of scope
 *  (i.e., when it is destroyed).
 *  Almost every function in VOS that returns a RefCounted object (e.g.
 *  any MetaObject or Vobject) increments that object's reference count
 *  before doing so. This means that you must use this class to store that
 *  object, or manually call RefCounted::release() on the object when you
 *  are done using it.   
 *
 *  Note that this class takes care of releasing your object automatically,
 *  not acquiring it. For example, if you assign (with =) a pointer (or another vRef) 
 *  from some vRef and then store that pointer (or other vRef) beyond the life of 
 *  the original vRef object, its reference count will be incorrect: call acquire() 
 *  on the object when you store the pointer (or other vRef).  
 *
 *  However, the copy constructor <emphasis>does</emphasis> acquire the RefCounted object.
 * 
 *  For more discussion and examples, see the VOS manual and the tutorial
 *  programs (in "apps/tutorials").
 */
template<class T> class vRef
{
private:
    T* ptr;
public:
    vRef() : ptr(0) { }
    vRef(T* x) : ptr(x) { }
    vRef(T& x) : ptr(&x) { }
    vRef(const vRef<T>& x) : ptr(x.ptr) { if(ptr) ptr->acquire(); }
    ~vRef() { if(ptr) ptr->release(); }

    T* operator=(T* x) { if(ptr) ptr->release();  ptr = x; return x; }
    T& operator=(T& x) { if(ptr) ptr->release();  ptr = &x; return x; }

    vRef<T>& operator=(const vRef<T>& x) {
        if(ptr) ptr->release();
        ptr = x.ptr;
        if(ptr) ptr->acquire();
        return *this;
    }

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

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

    void acquire() { ptr->acquire(); }
    void release() { ptr->release(); }
};
}

#endif

---