coherence/lang/ChainedHandleElement.hpp

/*
* ChainedHandleElement.hpp
*
* Copyright (c) 2000, 2009, Oracle and/or its affiliates. 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_CHAINED_HANDLE_ELEMENT_HPP
#define COH_CHAINED_HANDLE_ELEMENT_HPP

#include "coherence/lang/compatibility.hpp"

#include <stdlib.h>

COH_OPEN_NAMESPACE2(coherence,lang)

/**
* @internal
*
* The base class for TypedHandles, allowing for reference chaining.  Reference
* chaining is not thread-safe and thus may only be used for handles which are
* not shared across threads.
*
* @author mf  2008.10.20
*/
class ChainedHandleElement
    {
    protected:
        /**
        * Action to take on unlinking
        */
        typedef enum
            {
            ACTION_NONE   = 0, // no action required, chain still exists
            ACTION_FLIP   = 1, // unlink last handle from handle->view chain
            ACTION_DETACH = 2, // unlink final element of chain
            ACTION_ERROR  = 3  // corrupted chain, raise error
            } Action;


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

    protected:
        /**
        * Create an independent element.
        */
        ChainedHandleElement(bool fView)
            : m_fView(fView)
            {
            // new chain
            m_prev = m_next = this;
            }

        /**
        * Create a dependent element, adding it to a chain.
        */
        ChainedHandleElement(const ChainedHandleElement& that, bool fView)
            : m_prev(&that), m_next(that.m_next), m_fView(fView)
            {
            // add self to chain
            m_next->m_prev = m_prev->m_next = this;
            }

        /**
        * Create an optionally dependent element.
        */
        ChainedHandleElement(const ChainedHandleElement* that, bool fView)
            : m_fView(fView)
            {
            if (that)
                {
                // add self to chain
                m_prev = that;
                m_next = that->m_next;
                m_next->m_prev = m_prev->m_next = this;
                }
            else
                {
                // new chain
                m_prev = m_next = this;
                }
            }

        /**
        * No destructor, derived class must perform unlink and take resulting
        * action.
        */
        //~ChainedHandleElement()


    // ----- ChainedHandleElement interface ---------------------------------

    protected:
        /**
        * Unlink this element from the chain.
        *
        * @return the action to be taken
        */
        Action unlink()
            {
            Action nAction = this == m_prev
                ? this == m_next ? ACTION_DETACH : ACTION_ERROR
                : !m_fView && m_prev->m_fView && m_next->m_fView && scan()
                    ? ACTION_FLIP : ACTION_NONE;

            // unlink self from chain
            m_prev->m_next = m_next;
            m_next->m_prev = m_prev;

            // empty chain
            m_prev = m_next = this;

            return nAction;
            }

        /**
        * Link this element to a new chain.
        *
        * @param that  the element to link to
        *
        * @return the action to be taken
        */
        Action link(const ChainedHandleElement& that)
            {
            Action nAction = this == m_prev
                ? this == m_next ? ACTION_DETACH : ACTION_ERROR
                : !m_fView && m_prev->m_fView && m_next->m_fView && scan()
                    ? ACTION_FLIP : ACTION_NONE;

            // unlink self from chain
            m_prev->m_next = m_next;
            m_next->m_prev = m_prev;

            // link self into new chain
            m_prev = &that;
            m_next = that.m_next;

            m_next->m_prev = that.m_next = this;

            return nAction;
            }

        /**
        * Scan the chain for additional handles.
        *
        * The caller must be a handle, and have found views on both sides.
        *
        * @return true if this is the only handle in the chain
        */
        bool scan()
            {
            // The current element must be a handle, so we can scan the list
            // until we encounter a handle; if it is this element then there
            // are no other handles present. While this is a potentially
            // expensive call it is also rarely occurs on a non-trivial chain.
            // Since you cannot assign a Handle from a View this will only
            // happen if multiple Views are injected in the middle of a handle
            // chain. Overall this minimal rare cost is more than worth it as
            // it allows chaining of Handles and Views, which removes the far
            // more expensive (potentially atomic) reference count increment
            // for the common pattern of passing a Handle to a function which
            // takes a View.
            ChainedHandleElement const* pElm;
            for (pElm = m_prev; pElm->m_fView; pElm = pElm->m_prev);
            return pElm == this;
            }


    // ----- blocked methods ------------------------------------------------

    private:
        /**
        * Blocked dynamic allocation.
        */
        static void* operator new(size_t cb);


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

    protected:
        /**
        * The previous element in the chain.
        */
        mutable ChainedHandleElement const* m_prev;

        /**
        * The next element in the chain.
        */
        mutable ChainedHandleElement const* m_next;

        /**
        * Flag indicating if the associated handle is a view.
        */
        bool m_fView;
    };

COH_CLOSE_NAMESPACE2

#endif // COH_CHAINED_HANDLE_ELEMENT_HPP

Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.