coherence/lang/LifeCycle.hpp

/*
* LifeCycle.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_LIFE_CYCLE_HPP
#define COH_LIFE_CYCLE_HPP

#include "coherence/lang/compatibility.hpp"

#include <ostream>

COH_OPEN_NAMESPACE2(coherence,lang)


/**
* @internal
*
* LifeCycle is a data structure which maintains the reference counts and
* other key pieces of information related to an Object's life. It is
* limited to 64 bits of storage so that it may fit into a NativeAtomic64.
*
* This class is used as a snapshot of the NativeAtomic64 representing the
* Object's life-cycle. It is therefore safe to perform multiple
* unsynchronized reads/writes against the individual fields. The snapshot
* can then be written back to the Object's NativeAtomic64 life-cycle
*
* The specific layout of the bit-field is non-public and is subject to
* change.
*
* @author mf 2008.01.28
*/
union LifeCycle
    {
    // ---- constructors ----------------------------------------------------

    /**
    * Construct an uninitialized LifeCycle object.
    */
    LifeCycle()
        {
        }

    /**
    * Construct a LifeCycle object from a raw int64_t, allowing
    * initialization from a NativeAtomic64.
    *
    * @param lRaw  the 64-bit representation of the LifeCycle
    */
    LifeCycle(const int64_t lRaw)
        : m_lRaw(lRaw)
        {
        }


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

    /**
    * Automatic type conversion to int64_t, allowing a LifeCycle instance
    * to be stored within a NativeAtomic64.
    *
    * @return the int64_t representation of the LifeCycle
    */
    operator int64_t() const
        {
        return m_lRaw;
        }

    /**
    * Compare two LifeCycles for equality.
    *
    * @param that  the LifeCycle to compare against
    *
    * @return true if the LifeCycles are equal
    */
    bool operator==(const LifeCycle& that)
        {
        return m_lRaw == that.m_lRaw;
        }

    /**
    * Compare two LifeCycles for equality.
    *
    * @param that  the LifeCycle to compare against
    *
    * @return true if the LifeCycles are not equal
    */
    bool operator!=(const LifeCycle& that)
        {
        return m_lRaw != that.m_lRaw;
        }


    // ----- constants ------------------------------------------------------

    /**
    * Field identifiers.
    */
    typedef enum
        {
        LIFE_STATE,               // Object life state
        ESCAPE_STATE,             // Object thread-escape state
        MONITOR_STATE,            // Monitor inflation state
        WEAK_REFERENCE_STATE,     // WeakReference inflation state
        HANDLE_COUNT,             // Handle reference count
        VIEW_COUNT,               // View reference count
        MEMBER_LOCK_STATE,        // read/write lock state
        MEMBER_LOCK_READER_COUNT  // read/write lock active reader count
        } FieldId;

    /**
    * Monitor/WeakReference state constants.
    */
    typedef enum
        {
        CONSTRUCTING = 0, // pre onInit
        INITIALIZING = 1, // inside onInit()
        INITIALIZED  = 2, // post onInit()
        DESTRUCTING  = 3  // in delete
        } LifeStage;

    /**
    * Monitor/WeakReference state constants.
    */
    typedef enum
        {
        FLAT      = 0, // lazy element does not exist
        INFLATING = 1, // lazy initialization in progress
        INFLATED  = 2  // lazy element is usable
        } InflationState;

    /**
    * Member read/write lock state.
    */
    typedef enum
        {
        GATE_OPEN    = 0, // read locks may be acquired
        GATE_CLOSING = 1, // no new read locks may be acquired
        GATE_CLOSED  = 2  // no read locks held, no new read locks may be acquired
        } MemberLockState;

    /**
    * The per-attachment count for escaped handles.
    */
    enum
        {
        ESCAPED_INCREMENT = 2
        };

    /**
    * Limits.
    */
    enum
        {
        MAX_READ_LOCKS = 0xFF,    // maximum number of reader threads, before blocking
        MAX_HANDLES    = 0xFFFFF, // maximum number of handles to an Object
        MAX_VIEWS      = 0xFFFFF  // maximum number of views to an Object
        };


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

    /**
    * Raw uninterpreted bit field.
    */
    int64_t m_lRaw;

    /**
    * Bit-field representation of state.
    */
    struct
        {
        /**
        * The stage of life the object is in.
        */
        unsigned int nLifeStage : 2;

        /**
        * The thread-escape state of the object.
        */
        unsigned int fEscaped : 1;

        /**
        * The InflationState of the Object's monitor.
        *
        * @see InflationState
        */
        unsigned int nMonitor : 2;

        /**
        * The InflationState of the Object's WeakReference.
        *
        * @see InflationState
        */
        unsigned int nWeakReference : 2;

        /**
        * The number of Handles to the Object.
        *
        * A value of MAX_HANDLES is considered invalid and is used to
        * detect roll over.
        */
        unsigned int cHandle : 20; // if changed update MAX_HANDLES

        /**
        * The number of Views to the Object.
        *
        * A value of MAX_VIEWS is considered invalid and is used to
        * detect roll over.
        */
        unsigned int cView : 20; // if changed update MAX_VIEWS

        /**
        * The MemberLockState for the Object.
        *
        * @see MemberLockState
        */
        unsigned int nMemberWriteLockState: 2;

        /**
        * The number of member read locks held.
        *
        * A value of MAX_READ_LOCKS indicates that there are too many
        * readers and a new reader thread must wait even if the lock is
        * currently GATE_OPEN.
        */
        unsigned int cMemberReadLock : 8; // if changed update MAX_READ_LOCKS
        } value;
    };

/**
* Output a human-readable description of the LifeCycle to an output
* stream.
*
* @param out     the stream to write the description to
* @param nState  the state to write to the stream
*
* @return a reference to the supplied stream
*/
std::ostream& operator<<(std::ostream& out, const LifeCycle& nState);

COH_CLOSE_NAMESPACE2

#endif // COH_LIFE_CYCLE_HPP

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