path: root/indra/llcommon/llhandle.h

/**
* @file llhandle.h
* @brief "Handle" to an object (usually a floater) whose lifetime you don't
* control.
*
* $LicenseInfo:firstyear=2001&license=viewerlgpl$
* Second Life Viewer Source Code
* Copyright (C) 2010, Linden Research, Inc.
*
* 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;
* version 2.1 of the License only.
*
* 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., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
*
* Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
* $/LicenseInfo$
*/
#ifndef LLHANDLE_H
#define LLHANDLE_H

#include "llpointer.h"
#include "llrefcount.h"
#include "llexception.h"
#include <stdexcept>
#include <boost/type_traits/is_convertible.hpp>
#include <boost/utility/enable_if.hpp>
#include <boost/throw_exception.hpp>

/**
 * Helper object for LLHandle. Don't instantiate these directly, used
 * exclusively by LLHandle.
 */
class LLTombStone : public LLRefCount
{
public:
    LLTombStone(void* target = NULL) : mTarget(target) {}

    void setTarget(void* target) { mTarget = target; }
    void* getTarget() const { return mTarget; }
private:
    mutable void* mTarget;
};

/**
 *  LLHandles are used to refer to objects whose lifetime you do not control or influence.
 *  Calling get() on a handle will return a pointer to the referenced object or NULL,
 *  if the object no longer exists.  Note that during the lifetime of the returned pointer,
 *  you are assuming that the object will not be deleted by any action you perform,
 *  or any other thread, as normal when using pointers, so avoid using that pointer outside of
 *  the local code block.
 *
 *  https://wiki.lindenlab.com/mediawiki/index.php?title=LLHandle&oldid=79669
 *
 * The implementation is like some "weak pointer" implementations. When we
 * can't control the lifespan of the referenced object of interest, we can
 * still instantiate a proxy object whose lifespan we DO control, and store in
 * the proxy object a dumb pointer to the actual target. Then we just have to
 * ensure that on destruction of the target object, the proxy's dumb pointer
 * is set NULL.
 *
 * LLTombStone is our proxy object. LLHandle contains an LLPointer to the
 * LLTombStone, so every copy of an LLHandle increments the LLTombStone's ref
 * count as usual.
 *
 * One copy of the LLHandle, specifically the LLRootHandle, must be stored in
 * the referenced object. Destroying the LLRootHandle is what NULLs the
 * proxy's target pointer.
 *
 * Minor optimization: we want LLHandle's mTombStone to always be a valid
 * LLPointer, saving some conditionals in dereferencing. That's the
 * getDefaultTombStone() mechanism. The default LLTombStone object's target
 * pointer is always NULL, so it's semantically identical to allowing
 * mTombStone to be invalid.
 */
template <typename T>
class LLHandle
{
    template <typename U> friend class LLHandle;
    template <typename U> friend class LLHandleProvider;
public:
    LLHandle() : mTombStone(getDefaultTombStone()) {}

    template<typename U>
    LLHandle(const LLHandle<U>& other, typename boost::enable_if< typename boost::is_convertible<U*, T*> >::type* dummy = 0)
    : mTombStone(other.mTombStone)
    {}

    bool isDead() const
    {
        return mTombStone->getTarget() == NULL;
    }

    void markDead()
    {
        mTombStone = getDefaultTombStone();
    }

    T* get() const
    {
        return reinterpret_cast<T*>(mTombStone->getTarget());
    }

    friend bool operator== (const LLHandle<T>& lhs, const LLHandle<T>& rhs)
    {
        return lhs.mTombStone == rhs.mTombStone;
    }
    friend bool operator!= (const LLHandle<T>& lhs, const LLHandle<T>& rhs)
    {
        return !(lhs == rhs);
    }
    friend bool operator< (const LLHandle<T>& lhs, const LLHandle<T>& rhs)
    {
        return lhs.mTombStone < rhs.mTombStone;
    }
    friend bool operator> (const LLHandle<T>& lhs, const LLHandle<T>& rhs)
    {
        return lhs.mTombStone > rhs.mTombStone;
    }

protected:
    LLPointer<LLTombStone> mTombStone;

private:
    typedef T* pointer_t;
    static LLPointer<LLTombStone>& getDefaultTombStone()
    {
        static LLPointer<LLTombStone> sDefaultTombStone = new LLTombStone;
        return sDefaultTombStone;
    }
};

/**
 * LLRootHandle isa LLHandle which must be stored in the referenced object.
 * You can either store it directly and explicitly bind(this), or derive from
 * LLHandleProvider (q.v.) which automates that for you. The essential point
 * is that destroying the LLRootHandle (as a consequence of destroying the
 * referenced object) calls unbind(), setting the LLTombStone's target pointer
 * NULL.
 */
template <typename T>
class LLRootHandle : public LLHandle<T>
{
public:
    typedef LLRootHandle<T> self_t;
    typedef LLHandle<T> base_t;

    LLRootHandle(T* object) { bind(object); }
    LLRootHandle() {};
    ~LLRootHandle() { unbind(); }

    // this is redundant, since an LLRootHandle *is* an LLHandle
    //LLHandle<T> getHandle() { return LLHandle<T>(*this); }

    void bind(T* object)
    {
        // unbind existing tombstone
        if (LLHandle<T>::mTombStone.notNull())
        {
            if (LLHandle<T>::mTombStone->getTarget() == (void*)object) return;
            LLHandle<T>::mTombStone->setTarget(NULL);
        }
        // tombstone reference counted, so no paired delete
        LLHandle<T>::mTombStone = new LLTombStone((void*)object);
    }

    void unbind()
    {
        LLHandle<T>::mTombStone->setTarget(NULL);
    }

    //don't allow copying of root handles, since there should only be one
private:
    LLRootHandle(const LLRootHandle& other) {};
};

/**
 * Use this as a mixin for simple classes that need handles and when you don't
 * want handles at multiple points of the inheritance hierarchy
 */
template <typename T>
class LLHandleProvider
{
public:
    LLHandle<T> getHandle() const
    {
        // perform lazy binding to avoid small tombstone allocations for handle
        // providers whose handles are never referenced
        mHandle.bind(static_cast<T*>(const_cast<LLHandleProvider<T>* >(this)));
        return mHandle;
    }

    template <typename U>
    LLHandle<U> getDerivedHandle(typename boost::enable_if< typename boost::is_convertible<U*, T*> >::type* dummy = 0) const
    {
        LLHandle<U> downcast_handle;
        downcast_handle.mTombStone = getHandle().mTombStone;
        return downcast_handle;
    }

protected:
    typedef LLHandle<T> handle_type_t;
    LLHandleProvider()
    {
        // provided here to enforce T deriving from LLHandleProvider<T>
    }

private:
    mutable LLRootHandle<T> mHandle;
};



class LLCheckedHandleBase
{
public:
    class Stale : public LLException
    {
    public:
        Stale() :
            LLException("Attempt to access stale handle.")
        {}
    };

protected:
    LLCheckedHandleBase() { }

};

/**
 * This is a simple wrapper for Handles, allowing direct calls to the underlying
 * pointer. The checked handle will throw a Stale if an attempt
 * is made to access the object referenced by the handle and that object has
 * been destroyed.
 **/
template <typename T>
class LLCheckedHandle: public LLCheckedHandleBase
{
public:

    LLCheckedHandle(LLHandle<T> handle):
        mHandle(handle)
    { }

    /**
     * Test the underlying handle.  If it is no longer valid, throw a Stale exception.
     */
    void check() const
    {
        T* ptr = mHandle.get();
        if (!ptr)
            BOOST_THROW_EXCEPTION(Stale());
    }

    /**
     * Cast back to an appropriate handle
     */
    operator LLHandle<T>() const
    {
        return mHandle;
    }

    /**
     * Converts the LLCheckedHandle to a bool. Allows for if (chkdHandle) {}
     * Does not throw.
     */
    /*explicit*/ operator bool() const // explicit conversion operator not available with Linux compiler
    {
        return (mHandle.get() != NULL);
    }

    /**
     * Attempt to call a method or access a member in the structure referenced
     * by the handle.  If the handle no longer points to a valid structure
     * throw a Stale.
     */
    T* operator ->() const
    {
        T* ptr = mHandle.get();
        if (!ptr)
            BOOST_THROW_EXCEPTION(Stale());
        return ptr;
    }

private:

    LLHandle<T> mHandle;
};

#endif