coherence/lang/MemberHolder.hpp

/*
* MemberHolder.hpp
*
* Copyright 2001-2008 by Oracle. All rights reserved.
*
* Oracle is a registered trademarks of Oracle Corporation and/or its
* affiliates.
*
* This software is the confidential and proprietary information of Oracle
* Corporation. You shall not disclose such confidential and proprietary
* information and shall use it only in accordance with the terms of the
* license agreement you entered into with Oracle.
*
* This notice may not be removed or altered.
*/
#ifndef COH_MEMBER_HOLDER_HPP
#define COH_MEMBER_HOLDER_HPP

#include "coherence/lang/compatibility.hpp"

#include "coherence/lang/Object.hpp"
#include "coherence/lang/SmartMember.hpp"
#include "coherence/lang/SynchronizedMemberReadBlock.hpp"
#include "coherence/lang/SynchronizedMemberWriteBlock.hpp"
#include "coherence/lang/TypedHandle.hpp"
#include "coherence/lang/TypedHolder.hpp"

#include <ostream>

COH_OPEN_NAMESPACE2(coherence,lang)

class Object;
template<class T> class MemberHandle;
template<class T> class MemberView;


/**
* MemberHolder is a thread-safe handle implementation which supports
* referencing Objects as either Handles or Views. MemberHolder can safely be
* used in place of View but adds the ability to attempt a safe down cast to a
* Handle. This differs from the C++ const_cast in that the down cast will only
* succeed if the MemberHolder had been assigned from a Handle, an assignment
* from a View results in a MemberHolder whose down cast operation will throw
* a ClassCastException.
*
* MemberHolder is not for general use, instead it is a convience handle type
* which can be used for container like classes, which need to be able to
* contain both Handles and Views.
*
* @author mf  2008.01.09
*/
template<class T>
class MemberHolder
        : public SmartMember
    {
    // ----- typedefs -------------------------------------------------------

    public:
        /**
        * The type of the values the holder can reference.
        */
        typedef const T ValueType;

        /**
        * The Handle type for the referenced Object.
        */
        typedef typename T::Handle ValueHandle;

        /**
        * The View type for the referenced Object.
        */
        typedef typename T::View ValueView;

        /**
        * Result type for a non-const get operation.
        */
        typedef TypedHolder<T> GetType;


    // -------- constructors ------------------------------------------------

    public:
        /**
        * Construct a new MemberHolder referencing NULL via a handle.
        */
        MemberHolder(Object& oParent)
                : SmartMember(oParent), m_fView(false), m_po(NULL)
            {
            }

        /**
        * Construct a new MemberHolder refrencing specified Object via a
        * Handle or View.
        *
        * As a Handle is used, the MemberHolder can be used with the
        * cast() method to retrieve the Handle from the Holder.
        *
        * @param oParent  the self() on the object this data member is a
        *                 member of
        * @param th       a Handle or View to the Object to reference
        */
        template<class DT> MemberHolder(Object& oParent, const TypedHandle<DT>& th)
                : SmartMember(oParent), m_fView(false), m_po(NULL)
            {
            // use RTTI to identify the template type is a const
            if (typeid(DT*) == typeid(const DT*))
                {
                MemberHolder<T>::setView(th);
                }
            else
                {
                // if we are here then the type is non-const, the code still
                // must compile even when it is const, though it will never
                // run in that case. We cast-away constness for compilation,
                // and rely on the runtime check to choose the correct path.
                MemberHolder<T>::setHandle((T*) get_pointer(th));
                }
            }

        /**
        * Construct a new MemberHolder refrencing the same Object (and in
        * the same manner) as the specified TypedHolder.
        *
        * @param oParent  the self() on the object this data member is a
        *                 member of
        * @param th       the TypedHolder to initialize from
        *
        */
        template<class DT> MemberHolder(Object& oParent, const TypedHolder<DT>& th)
                : SmartMember(oParent), m_fView(false), m_po(NULL)
            {
            operator=(th);
            }

        /**
        * Construct a new MemberHolder refrencing the same Object (and in
        * the same manner) as the specified MemberHolder.
        *
        * @param oParent  the self() on the object this data member is a
        *                 member of
        * @param that     the MemberHolder to initialize from
        */
        template<class DT> MemberHolder(Object& oParent, const MemberHolder<DT>& that)
                : SmartMember(oParent), m_fView(false), m_po(NULL)
            {
            operator=(that);
            }

        /**
        * Destroy the MemberHolder.
        */
        ~MemberHolder()
            {
            try
                {
                setHandle(ValueHandle());
                }
            catch (const std::exception& e)
                {
                // Exception::View is not a known type within this file
                std::cerr << "Error during ~MemberHolder: " << e.what() << std::endl;
                return; // can't re-throw from within destructor
                }
            }

    protected:
        /**
        * Construct a MemberHolder without any associated parent.
        *
        * The new MemberHolder is not useable until the parent is specified.
        */
        MemberHolder()
            : SmartMember(), m_fView(false), m_po(NULL)
            {
            }

    private:
        /**
        * Blocked copy constructor.
        */
        MemberHolder(const MemberHolder&);


    // ----- operators ------------------------------------------------------

    public:
        /**
        * Assign this MemberHolder to refrence the same Object (and in the
        * same manner) as the specified MemberHolder.
        *
        * @param that  the MemberHolder to assign from
        *
        * @return a reference to this MemberHolder
        */
        MemberHolder& operator=(const MemberHolder& that)
            {
            operator=((TypedHolder<T>) that); // assign from snapshot
            return *this;
            }

        /**
        * Assign this MemberHolder to refrence the same Object (and in the
        * same manner) as the specified MemberHolder.
        *
        * @param mh  the TypedHolder to assign from
        *
        * @return a reference to this MemberHolder
        */
        template<class DT> MemberHolder& operator=(const MemberHolder<DT>& mh)
            {
            operator=((TypedHolder<DT>) mh);
            return *this;
            }

        /**
        * Assign this MemberHolder to refrence the same Object (and in the
        * same manner) as the specified MemberHolder.
        *
        * @param th  the TypedHolder to assign from
        *
        * @return a reference to this MemberHolder
        */
        template<class DT> MemberHolder& operator=(const TypedHolder<DT>& th)
            {
            set(th);
            return *this;
            }

        /**
        * Assign this MemberHolder to refrence the same Object (and in the
        * same manner) as the specified MemberHolder.
        *
        * @param h  the TypedHandle to assign from
        *
        * @return a reference to this MemberHolder
        */
        template<class DT> MemberHolder& operator=(const TypedHandle<DT>& h)
            {
            // use RTTI to identify the template type is a const
            if (typeid(DT*) == typeid(const DT*))
                {
                setView(h);
                }
            else
                {
                // if we are here then the type is non-const, the code still
                // must compile even when it is const, though it will never
                // run in that case. We cast-away constness for compilation,
                // and rely on the runtime check to choose the correct path.
                setHandle((T*) get_pointer(h));
                }
            return *this;
            }

        template<class DT>
        MemberHolder& operator=(MemberHandle<DT>& mh)
            {
            return operator=((ValueHandle) mh);
            }

        template<class DT>
        MemberHolder& operator=(const MemberHandle<DT>& mh)
            {
            return operator=((ValueView) mh);
            }

        template<class DT>
        MemberHolder& operator=(const MemberView<DT>& mv)
            {
            return operator=((ValueView) mv);
            }

        /**
        * Assign this MemberHolder to refrence the same Object (and in the
        * same manner) as the specified pointer.
        *
        * @param cp  the pointer to assign from
        *
        * @return a reference to this MemberHolder
        */
        MemberHolder& operator=(const T* cp)
            {
            return operator=((ValueView) cp);
            }

        /**
        * Return a View to the referenced Object.
        *
        * @return a View to the referenced Object
        */
        operator ValueView() const
            {
            SynchronizedMemberReadBlock syncRead(getParent());
            return m_po; // view assignment, could throw
            }

        /**
        * Return a View to the referenced Object.
        *
        * @return a View to the referenced Object
        */
        template<class PT>
        operator TypedHandle<const PT>() const
            {
            return (ValueView) *this;
            }

        /**
        * Return a TypedHolder to the referenced Object.
        *
        * @return a TypedHolder to the referenced Object
        */
        template<class PT>
        operator TypedHolder<PT>() const
            {
            return get();
            }

        /**
        * Derefrence the MemberHolder.
        *
        * @return a const pointer to the referenced Object
        */
        ValueView operator->() const
            {
            return (ValueView) *this;
            }

        /**
        * Compare the supplied holder to this holder.
        *
        * @param mh  the holder to compare against
        *
        * @return true iff the same object is referenced
        */
        template<class AT>
        bool operator==(const MemberHolder<AT>& mh) const
            {
            typename MemberHolder<AT>::ValueView v = mh;
            return operator==(v);
            }

        /**
        * Compare the supplied holder to this holder.
        *
        * @param mh  the holder to compare against
        *
        * @return true iff different objects are referenced
        */
        template<class AT>
        bool operator!=(const MemberHolder<AT>& mh) const
            {
            return !operator==(mh);
            }

        /**
        * Compare the supplied holder to this holder.
        *
        * @param th  the holder to compare against
        *
        * @return true iff the same object is referenced
        */
        template<class AT>
        bool operator==(const TypedHolder<AT>& th) const
            {
            return operator==(get_pointer((typename TypedHolder<AT>::ValueView) th));
            }

        /**
        * Compare the supplied holder to this holder.
        *
        * @param th  the holder to compare against
        *
        * @return true iff different objects are referenced
        */
        template<class AT>
        bool operator!=(const TypedHolder<AT>& th) const
            {
            return !operator==(th);
            }

        /**
        * Compare the supplied handle to this holder.
        *
        * @param h  the handle to compare against
        *
        * @return true iff the same object is referenced
        */
        template<class AT>
        bool operator==(const TypedHandle<AT>& h) const
            {
            return operator==(get_pointer(h));
            }

        /**
        * Compare the supplied handle to this holder.
        *
        * @param h  the handle to compare against
        *
        * @return true iff the different objects are referenced
        */
        template<class AT>
        bool operator!=(const TypedHandle<AT>& h) const
            {
            return !operator==(h);
            }

        /**
        * Compare the supplied pointer to this holder.
        *
        * @param cpThat  the pointer to compare against
        *
        * @return true iff the same object is referenced
        */
        bool operator==(const Object* cpThat) const
            {
            SynchronizedMemberReadBlock syncRead(getParent());
            return ((const Object*) m_po) == cpThat;
            }

        /**
        * Compare the supplied pointer to this holder.
        *
        * @param cpThat  the pointer to compare against
        *
        * @return true iff different objects are referenced
        */
        bool operator!=(const Object* cpThat) const
            {
            return !operator==(cpThat);
            }


    // ----- helper methods -------------------------------------------------

    protected:
        /**
        * Set the Holder to reference an Object via a View.
        *
        * @param v      the View to the Object to reference
        * @param pSync  the synch block to delegate to or NULL to create one
        */
        void setView(const TypedHandle<const T>& v, SynchronizedMemberWriteBlock *pSync = NULL)
            {
            const T* cpNew    = get_pointer(v);
            const T* cpAttach = (NULL == cpNew || NULL == cpNew->_attach() ? NULL : cpNew);
            const T* cpDetach = NULL;
            T*       pDetach  = NULL;

            // sync block
                {
                SynchronizedMemberWriteBlock syncWrite(getParent(), pSync);
                if (m_fView)
                    {
                    cpDetach = m_po;
                    }
                else
                    {
                    pDetach = m_po;
                    }

                m_po    = const_cast<T*>(cpAttach);
                m_fView = cpAttach != NULL;
                }

            if (pDetach)
                {
                pDetach->_detach();
                }
            else if (cpDetach)
                {
                cpDetach->_detach();
                }
            }

        /**
        * Set the Holder to reference an Object via a Handle.
        *
        * @param h      the Handle to the Object to reference
        * @param pSync  the sync block to delegate to or NULL to create one
        */
        void setHandle(const TypedHandle<T>& h, SynchronizedMemberWriteBlock *pSync = NULL)
            {
            T*       pNew     = get_pointer(h);
            T*       pAttach  = (NULL == pNew || NULL == pNew->_attach() ? NULL : pNew);
            T*       pDetach  = NULL;
            const T* cpDetach = NULL;

            // sync block
                {
                SynchronizedMemberWriteBlock syncWrite(getParent(), pSync);
                if (m_fView)
                    {
                    cpDetach = m_po;
                    }
                else
                    {
                    pDetach = m_po;
                    }

                m_po    = pAttach;
                m_fView = false;
                }

            if (pDetach)
                {
                pDetach->_detach();
                }
            else if (cpDetach)
                {
                cpDetach->_detach();
                }
            }

        /**
        * Set the MemberHolder to reference the same Object as the specified
        * TypedHolder.
        *
        * @param th     the TypedHolder to copy
        * @param pSync  the sync block to delegate to or NULL to create one
        */
        template<class DT> void set(const TypedHolder<DT>& th, SynchronizedMemberWriteBlock *pSync = NULL)
            {
            ValueHandle hThat = cast<typename DT::Handle>(th, false);
            if (NULL == hThat)
                {
                setView(th, pSync);
                }
            else
                {
                setHandle(hThat, pSync);
                }
            }

        /**
         * Return a TypedHolder referencing the same Object as this
         * MemberHolder
         *
         * @param pSync  the sync block to delegate to or NULL to create one
         *
         * @return a TypedHolder referecning the same Object as this
         *         MemberHolder
         */
        TypedHolder<T> get(SynchronizedMemberReadBlock* pSync = NULL) const
            {
            SynchronizedMemberReadBlock syncRead(getParent(), pSync);
            if (m_fView)
                {
                return (ValueView) m_po;
                }
            return (ValueHandle) m_po;
            }


    // ----- data members ---------------------------------------------------

    private:
        /**
        * True iff a View is held, i.e. down casting to a Handle is not
        * allowed.
        */
        bool m_fView;

        /**
        * The referenced Object.
        */
        T* m_po;


    // ----- friends --------------------------------------------------------

    /**
    * @internal
    */
    template<class> friend class Array;

    /**
    * @internal
    */
    friend class SynchronizedMemberReadBlock;

    /**
    * @internal
    */
    friend class SynchronizedMemberWriteBlock;
    };


// ----- non-member operators and functions ---------------------------------

/**
* Output a human-readable description of the given MemberHolder to the
* specified stream.
*
* @param out  the stream used to output the description
* @param th   the MemberHolder to describe
*
* @return the supplied stream
*/
template<class T> std::ostream& operator<<(std::ostream& out, const MemberHolder<T>& th)
    {
    out << (typename T::View) th;
    return out;
    }

/**
* Assign the specified holder to NULL.
*
* @param mh the holder to clear
*/
template<class T> void clear_handle(MemberHolder<T>& mh)
    {
    static TypedHandle<T> hNull;
    mh = hNull;
    }

/**
* Return true if the supplied holder equals NULL.
*
* @param mh  the holder to test
*
* @return true iff the supplied holder equals NULL
*/
template<class T>
bool is_null(const MemberHolder<T>& mh)
    {
    return NULL == mh;
    }

/**
* Perform a dynamic cast the pointer associated with the MemberHolder
* to a the specified handle/view type.
*
* @param mh      the MemberHolder from which to perform the cast
* @param fThrow  true if an exception is to be thrown on a failed cast
*
* @return the casted pointer, or NULL if the cast fails and fThrow is false
*
* @throws ClassCastException if the cast fails and fThrow is true
*/
template<class D, class T>
D cast(const MemberHolder<T>& mh, bool fThrow = true)
    {
    return cast<D>((TypedHolder<T>) mh, fThrow);
    }

/**
* Perform an instanceof check on a handle or view.
*
* @param th  the MemberHolder from which to perform the test
*
* @return true if the supplied handle is an instance of the specified type
*/
template<class D, class T>
bool instanceof(const MemberHolder<T>& mh)
    {
    return instanceof<D>((TypedHolder<T>) mh);
    }

/**
* Compare a handle to a holder.
*
* @param h   handle to compare
* @param mh  holder to compare
*
* @return true if both reference the same Object
*/
template<class AT, class T>
bool operator==(const TypedHandle<AT>& h, const MemberHolder<T>& mh)
    {
    return mh == h;
    }

/**
* Compare a Object pointer to a holder.
*
* @param cpo  handle to compare
* @param mh   holder to compare
*
* @return true if both reference the same Object
*/
template<class T>
bool operator==(const Object* cpo, const MemberHolder<T>& mh)
    {
    return mh == cpo;
    }

/**
* Compare a handle to a holder.
*
* @param h   handle to compare
* @param mh  holder to compare
*
* @return true if each references a different Object
*/
template<class AT, class T>
bool operator!=(const TypedHandle<AT>& h, const MemberHolder<T>& mh)
    {
    return mh != h;
    }

/**
* Compare a Object pointer to a holder.
*
* @param cpo  handle to compare
* @param mh   holder to compare
*
* @return true if each references a different Object
*/
template<class T>
bool operator!=(const Object* cpo, const MemberHolder<T>& mh)
    {
    return mh != cpo;
    }

COH_CLOSE_NAMESPACE2

#endif // COH_MEMBER_HOLDER_HPP

Copyright (c) 2000-2008 Oracle. All rights reserved.