00001 /* 00002 * LifeCycle.hpp 00003 * 00004 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_LIFE_CYCLE_HPP 00017 #define COH_LIFE_CYCLE_HPP 00018 00019 #include "coherence/lang/compatibility.hpp" 00020 00021 #include <ostream> 00022 00023 COH_OPEN_NAMESPACE2(coherence,lang) 00024 00025 00026 /** 00027 * @internal 00028 * 00029 * LifeCycle is a data structure which maintains the reference counts and 00030 * other key pieces of information related to an Object's life. It is 00031 * limited to 64 bits of storage so that it may fit into a NativeAtomic64. 00032 * 00033 * This class is used as a snapshot of the NativeAtomic64 representing the 00034 * Object's life-cycle. It is therefore safe to perform multiple 00035 * unsynchronized reads/writes against the individual fields. The snapshot 00036 * can then be written back to the Object's NativeAtomic64 life-cycle 00037 * 00038 * The specific layout of the bit-field is non-public and is subject to 00039 * change. 00040 * 00041 * @author mf 2008.01.28 00042 */ 00043 union LifeCycle 00044 { 00045 // ---- constructors ---------------------------------------------------- 00046 00047 /** 00048 * Construct an uninitialized LifeCycle object. 00049 */ 00050 LifeCycle() 00051 { 00052 } 00053 00054 /** 00055 * Construct a LifeCycle object from a raw int64_t, allowing 00056 * initialization from a NativeAtomic64. 00057 * 00058 * @param lRaw the 64-bit representation of the LifeCycle 00059 */ 00060 LifeCycle(const int64_t lRaw) 00061 : m_lRaw(lRaw) 00062 { 00063 } 00064 00065 00066 // ----- operators ------------------------------------------------------ 00067 00068 /** 00069 * Automatic type conversion to int64_t, allowing a LifeCycle instance 00070 * to be stored within a NativeAtomic64. 00071 * 00072 * @return the int64_t representation of the LifeCycle 00073 */ 00074 operator int64_t() const 00075 { 00076 return m_lRaw; 00077 } 00078 00079 /** 00080 * Compare two LifeCycles for equality. 00081 * 00082 * @param that the LifeCycle to compare against 00083 * 00084 * @return true if the LifeCycles are equal 00085 */ 00086 bool operator==(const LifeCycle& that) 00087 { 00088 return m_lRaw == that.m_lRaw; 00089 } 00090 00091 /** 00092 * Compare two LifeCycles for equality. 00093 * 00094 * @param that the LifeCycle to compare against 00095 * 00096 * @return true if the LifeCycles are not equal 00097 */ 00098 bool operator!=(const LifeCycle& that) 00099 { 00100 return m_lRaw != that.m_lRaw; 00101 } 00102 00103 00104 // ----- constants ------------------------------------------------------ 00105 00106 /** 00107 * Field identifiers. 00108 */ 00109 typedef enum 00110 { 00111 life_state, // Object life state 00112 escape_state, // Object thread-escape state 00113 monitor_state, // Monitor inflation state 00114 weak_reference_state, // WeakReference inflation state 00115 handle_count, // Handle reference count 00116 view_count, // View reference count 00117 member_lock_state, // read/write lock state 00118 member_lock_reader_count // read/write lock active reader count 00119 } FieldId; 00120 00121 /** 00122 * Monitor/WeakReference state constants. 00123 */ 00124 typedef enum 00125 { 00126 constructing = 0, // pre onInit 00127 initializing = 1, // inside onInit() 00128 initialized = 2, // post onInit() 00129 destructing = 3 // in delete 00130 } LifeStage; 00131 00132 /** 00133 * Monitor/WeakReference state constants. 00134 */ 00135 typedef enum 00136 { 00137 flat = 0, // lazy element does not exist 00138 inflating = 1, // lazy initialization in progress 00139 inflated = 2 // lazy element is usable 00140 } InflationState; 00141 00142 /** 00143 * Member read/write lock state. 00144 */ 00145 typedef enum 00146 { 00147 gate_open = 0, // read locks may be acquired 00148 gate_closing = 1, // no new read locks may be acquired 00149 gate_closed = 2 // no read locks held, no new read locks may be acquired 00150 } MemberLockState; 00151 00152 /** 00153 * The per-attachment count for escaped handles. 00154 */ 00155 enum 00156 { 00157 escaped_increment = 2 00158 }; 00159 00160 /** 00161 * Limits. 00162 */ 00163 enum 00164 { 00165 max_read_locks = 0xFF, // maximum number of reader threads, before blocking 00166 max_handles = 0xFFFFF, // maximum number of handles to an Object 00167 max_views = 0xFFFFF // maximum number of views to an Object 00168 }; 00169 00170 00171 // ----- data members --------------------------------------------------- 00172 00173 /** 00174 * Raw uninterpreted bit field. 00175 */ 00176 int64_t m_lRaw; 00177 00178 /** 00179 * Bit-field representation of state. 00180 */ 00181 struct 00182 { 00183 /** 00184 * The stage of life the object is in. 00185 */ 00186 unsigned int nLifeStage : 2; 00187 00188 /** 00189 * The thread-escape state of the object. 00190 */ 00191 unsigned int fEscaped : 1; 00192 00193 /** 00194 * The InflationState of the Object's monitor. 00195 * 00196 * @see InflationState 00197 */ 00198 unsigned int nMonitor : 2; 00199 00200 /** 00201 * The InflationState of the Object's WeakReference. 00202 * 00203 * @see InflationState 00204 */ 00205 unsigned int nWeakReference : 2; 00206 00207 /** 00208 * The number of Handles to the Object. 00209 * 00210 * A value of max_handles is considered invalid and is used to 00211 * detect roll over. 00212 */ 00213 unsigned int cHandle : 20; // if changed update max_handles 00214 00215 /** 00216 * The number of Views to the Object. 00217 * 00218 * A value of max_views is considered invalid and is used to 00219 * detect roll over. 00220 */ 00221 unsigned int cView : 20; // if changed update max_views 00222 00223 /** 00224 * The MemberLockState for the Object. 00225 * 00226 * @see MemberLockState 00227 */ 00228 unsigned int nMemberWriteLockState: 2; 00229 00230 /** 00231 * The number of member read locks held. 00232 * 00233 * A value of max_read_locks indicates that there are too many 00234 * readers and a new reader thread must wait even if the lock is 00235 * currently gate_open. 00236 */ 00237 unsigned int cMemberReadLock : 8; // if changed update max_read_locks 00238 } value; 00239 }; 00240 00241 /** 00242 * Output a human-readable description of the LifeCycle to an output 00243 * stream. 00244 * 00245 * @param out the stream to write the description to 00246 * @param nState the state to write to the stream 00247 * 00248 * @return a reference to the supplied stream 00249 */ 00250 std::ostream& operator<<(std::ostream& out, const LifeCycle& nState); 00251 00252 COH_CLOSE_NAMESPACE2 00253 00254 #endif // COH_LIFE_CYCLE_HPP