coherence/lang/MemberHandle.hpp

/*
* MemberHandle.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_HANDLE_HPP
#define COH_MEMBER_HANDLE_HPP

#include "coherence/lang/compatibility.hpp"

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

#include <ostream>
#include <sstream>

COH_OPEN_NAMESPACE2(coherence,lang)

template<class> class MemberView;


/**
* MemberHandle is a thread-safe handle used by an Object to reference its
* non-const child Objects.
*
* MemberHandles transfer the constness of their parent Object. When a
* MemberHandle is accessed from within a const method of the enclosing
* "parent" class, it will only provide const access to the Object which it
* references. If the enclosing Object becomes only accessed via views the
* MemberHandle will also automatically, and permantently switch its reference
* type from a handle to a view.
*
* Note: In the rare case that a MemberHandle is declared via the mutable
*       keyword, the MemberHandle must be informed of this fact by setting
*       fMutable to true during construction.
*
* @author mf  2007.07.05
*
* @see MemberView
* @see MemberHolder
*/
template<class T>
class MemberHandle
        : public SmartMember
    {
    // ----- typedefs -------------------------------------------------------

    public:
        /**
        * The type of the values the handle can reference.
        */
        typedef 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 ValueHandle GetType;

        /**
        * Result type for a non-const get operation.
        */
        typedef ValueView ConstGetType;

        /**
        * Flip states
        */
        typedef enum
            {
            UNFLIPPED = 0,
            FLIPPED   = 1,
            MUTABLE   = 2
            };


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

    public:
        /**
        * Construct a new MemberHandle referencing NULL via a handle.
        *
        */
        MemberHandle(Object& oParent)
                : SmartMember(oParent), m_po(NULL), m_nFlipped(UNFLIPPED)
            {
            }

        /**
        * Construct a new MemberHandle referencing the specified Object via
        * a handle.
        *
        * @param oParent   the Object to which this member belongs
        * @param h         the handle to the Object to reference
        * @param fMutable  true iff the member is declared mutable
        */
        template<class DH>
        MemberHandle(Object& oParent, const DH& h, bool fMutable = false)
                : SmartMember(oParent), m_po(NULL), m_nFlipped(fMutable ? MUTABLE : UNFLIPPED)
            {
            set(h);
            }

        /**
        * Destroy the MemberHandle.
        */
        ~MemberHandle()
            {
            T*     po;
            int8_t nFlipped;

                {
                SynchronizedMemberWriteBlock syncWrite(getParent());
                po       = m_po;
                nFlipped = m_nFlipped;
                m_po     = NULL;
                }

            if (NULL != po)
                {
                try
                    {
                    if (nFlipped == FLIPPED)
                        {
                        ((const T*) po)->_detach();
                        }
                    else
                        {
                        po->_detach();
                        }
                    }
                catch (const std::exception& e)
                    {
                    // Exception::View is not a known type within this file
                    std::cerr << "Error during ~MemberHandle: " << e.what() << std::endl;
                    return; // can't re-throw from within destructor
                    }
                }
            }

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


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

    public:
        /**
        * Assign this MemberHandle to refrence the same Object as the specified
        * MemberHandle.
        *
        * @param that  the MemberHandle to assign from
        *
        * @return a reference to this MemberHandle
        */
        MemberHandle& operator=(MemberHandle& that)
            {
            operator=((ValueHandle) that); // assign from snapshot
            return *this;
            }

        /**
        * Assign this MemberHandle to refrence the same Object as the specified
        * MemberHandle.
        *
        * @param mv  the MemberHandle to assign from
        *
        * @return a reference to this MemberHandle
        */
        template<class DT> MemberHandle& operator=(const MemberHandle<DT>& mv)
            {
            operator=((TypedHandle<DT>) mv);
            return *this;
            }

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

        /**
        * Assign this MemberHandle to refrence the same Object as the specified
        * MemberHolder.
        *
        * @param mh  the MemberHolder to assign from
        *
        * @return a reference to this MemberHandle
        */
        template<class DT> MemberHandle& operator=(const MemberHolder<DT>& mh)
            {
            set(cast<typename DT::Handle>(mh));
            return *this;
            }

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

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

        /**
        * Return a View to the referenced Object.
        *
        * @return a View to the referenced Object
        */
        operator ValueView() const
            {
            return get();
            }

        /**
        * Return a Handle to the referenced Object.
        *
        * @return a Handle to the referenced Object
        */
        operator ValueHandle()
            {
            return get();
            }

        /**
        * 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 Handle to the referenced Object.
        *
        * @return a Handle to the referenced Object
        */
        template<class PT>
        operator TypedHandle<PT>()
            {
            return (ValueHandle) *this;
            }

        /**
        * @internal COHCPP-284: this conversion is disabled to avoid the
        *           automatic demotion of MemberHandles to Views when passing
        *           them to create() methods which take a Holder.  Disabling
        *           this method forces the user to perform an explicit
        *           handle based conversion.
        *
        * Return a TypedHolder to the referenced Object.
        *
        * @return a TypedHolder to the referenced Object
        *
        */
        /*template<class PT>
        operator TypedHolder<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>()
            {
            return (ValueHandle) *this;
            }

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

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

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

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

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

        /**
        * Compare the supplied MemberHolder to this MemberHandle.
        *
        * @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 MemberView to this MemberHandle.
        *
        * @param mv  the MemberVeiw to compare against
        *
        * @return true iff the same object is referenced
        */
        template<class AT>
        bool operator==(const MemberView<AT>& mv) const
            {
            typename MemberView<AT>::ValueView v = mv;
            return operator==(v);
            }

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

        /**
        * Compare the supplied holder to this handle.
        *
        * @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 handle.
        *
        * @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 handle.
        *
        * @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 handle.
        *
        * @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 handle.
        *
        * @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 handle.
        *
        * @param cpThat  the pointer to compare against
        *
        * @return true iff different objects are referenced
        */
        bool operator!=(const Object* cpThat) const
            {
            return !operator==(cpThat);
            }

    private:
        /**
        * Blocked assingment operator.
        */
        MemberHandle<T>& operator=(const MemberHandle<T>&);


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

    protected:
        /**
        * Set the MemberHandle to reference the same Object as the supplied
        * Handle.
        *
        * @param h      the handle to copy
        * @param pSync  optional external SyncornizedMemberBlock to use
        *               to avoid internal synchronization.
        */
        void set(const ValueHandle& h, SynchronizedMemberWriteBlock* pSync = NULL)
            {
            T*      po      = get_pointer(h);
            Object* pAttach = po == NULL ? NULL : po->_attach();
            T*      pDetach = NULL;

            // sync block
                {
                SynchronizedMemberWriteBlock syncWrite(getParent(), pSync);
                COH_ENSURE(m_nFlipped != FLIPPED);
                pDetach = m_po;
                m_po = NULL == pAttach ? NULL : po;
                }

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

        /**
        * Return a View to the referenced Object.
        *
        * @param pSync  optional external SyncornizedMemberReadBlock to use
        *               to avoid internal synchronization.
        *
        * @return a View to the referenced Object
        */
        ValueView get(SynchronizedMemberReadBlock* pSync = NULL) const
            {
            SynchronizedMemberReadBlock syncRead(getParent(), pSync);
            return (const T*) m_po;
            }

        /**
        * Return a Handle to the referenced Object.
        *
        * @param pSync  optional external SyncornizedMemberReadBlock to use
        *               to avoid internal synchronization.
        *
        * @return a Handle to the referenced Object
        */
        ValueHandle get(SynchronizedMemberReadBlock* pSync = NULL)
            {
            SynchronizedMemberReadBlock syncRead(getParent(), pSync);
            if (m_nFlipped != FLIPPED)
                {
                return m_po; // handle assignement, could throw
                }

            COH_THROW (IllegalStateException::
                create("attempt to access handle from flipped MemberHandle"));
            }

        /**
        * Flip the MemberHandle from a Handle based to a View based
        * reference. Once flipped the MemberHandle will no longer support
        * changing the reference or returning a Handle to the referenced
        * Object.
        */
        void flipHandle()
            {
            T*     po = NULL;
            int8_t nFlipped;

                {
                SynchronizedMemberWriteBlock syncWrite(getParent());
                nFlipped = m_nFlipped;

                switch (nFlipped)
                    {
                    case UNFLIPPED:
                        po         = m_po;
                        m_nFlipped = FLIPPED;
                        break;

                    case FLIPPED:
                        // no op
                        break;

                    case MUTABLE:
                    default:
                        COH_THROW (IllegalStateException::create("unflippable MemberHandle"));
                    }
                }

            // re-attach as const, then detach the old reference
            if (NULL != po)
                {
                ((const T*) po)->_attach();
                po->_detach();
                }
            }


    // ----- SmartMember interface ------------------------------------------

    protected:

        /**
        * {@inheritDoc}
        *
        * The MemberHandle is automatically flipped when the parent Object
        * bcomes only referenced via consts.
        */
        virtual void onConst()
            {
            if (m_nFlipped == UNFLIPPED)
                {
                flipHandle();
                }
            SmartMember::onConst();
            }


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

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

        /**
        * The flip state of the MemberHandle.
        */
        int8_t m_nFlipped;


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

    /**
    * @internal
    */
    template<class D, class H> friend D cast(MemberHandle<T>& mh, bool fTest);

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

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


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

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

/**
* Assign the specified handle to NULL.
*
* @param th the handle to clear
*/
template<class T> void clear_handle(MemberHandle<T>& mh)
    {
    mh = typename MemberHandle<T>::ValueHandle(NULL);
    }

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

/**
* Perform a dynamic cast the pointer associated with the MemberHandle
* to a the specified handle/view type.
*
* @param mh      the MemberHandle 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(MemberHandle<T>& mh, bool fThrow = true)
    {
    return cast<D>((typename MemberHandle<T>::ValueHandle) mh, fThrow);
    }

/**
* Perform a dynamic cast the pointer associated with the MemberHandle
* to a the specified handle/view type.
*
* @param mh      the MemberHandle 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 MemberHandle<T>& mh, bool fThrow = true)
    {
    return cast<D>((typename MemberHandle<T>::ValueView) mh, fThrow);
    }

/**
* Perform an instanceof check on a MemberHandle.
*
* @param mh  the MemberHandle 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(MemberHandle<T>& mh)
    {
    return NULL != cast<D>(mh, false);
    }

/**
* Perform an instanceof check on a MemberHandle.
*
* @param mh  the MemberHandle 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 MemberHandle<T>& mh)
    {
    return NULL != cast<D>(mh, false);
    }

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

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

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

/**
* Compare a Object pointer to a MemberHandle.
*
* @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 MemberHandle<T>& mh)
    {
    return mh != cpo;
    }

COH_CLOSE_NAMESPACE2

#endif // COH_MEMBER_HANDLE_HPP

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