00001 /* 00002 * System.hpp 00003 * 00004 * Copyright (c) 2000, 2014, 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_SYSTEM_HPP 00017 #define COH_SYSTEM_HPP 00018 00019 #include "coherence/lang/compatibility.hpp" 00020 00021 #include "coherence/lang/abstract_spec.hpp" 00022 #include "coherence/lang/HeapAnalyzer.hpp" 00023 #include "coherence/lang/ObjectArray.hpp" 00024 #include "coherence/lang/String.hpp" 00025 00026 COH_OPEN_NAMESPACE2(coherence,lang) 00027 00028 00029 /** 00030 * A collection of general purpose utility methods. 00031 * 00032 * @author mf 2007.12.19 00033 */ 00034 class COH_EXPORT System 00035 : public abstract_spec<System> 00036 { 00037 // ----- constructors --------------------------------------------------- 00038 00039 private: 00040 /** 00041 * Blocked constructor. 00042 */ 00043 System(); 00044 00045 00046 // ----- System interface ----------------------------------------------- 00047 00048 public: 00049 /** 00050 * Runs the garbage collector. 00051 * <p> 00052 * While most managed objects are automatically reclaimed when their 00053 * reference count reaches zero, some special case objects utilize 00054 * deferred automatic cleanup. Calling this method will expedite this 00055 * deferred cleanup. 00056 * 00057 * @param fFull true iff an exhaustive collection is desired 00058 */ 00059 static void gc(bool fFull = false); 00060 00061 /** 00062 * Return the number of milliseconds which have elapsed since the 00063 * process was started. 00064 * 00065 * @return the number of milliseconds which have elapsed since the 00066 * process was started 00067 */ 00068 static int64_t upTimeMillis(); 00069 00070 /** 00071 * Return the elapsed milliseconds since midnight January 1, 1970 UTC. 00072 * 00073 * This function does not guard against the clock rolling back or 00074 * jumping forward. 00075 * 00076 * @return the elapsed milliseconds 00077 */ 00078 static int64_t currentTimeMillis(); 00079 00080 /** 00081 * Returns a "safe" current time in milliseconds. 00082 * 00083 * Unlike the #currentTimeMillis() this method guarantees that the 00084 * time never "goes back". 00085 * 00086 * More specifically, when called twice on the same thread, the second 00087 * call will never return a value that is less then the value returned 00088 * by the first call. If a system time correction becomes necessary, an 00089 * attempt will be made to gradually compensate the returned value, so 00090 * in the long run the value returned by this method is the same as the 00091 * system time. 00092 * 00093 * Additionally, the following always holds true: 00094 * <pre> 00095 * System::safeTimeMillis() >= System::currentTimeMillis(); 00096 * </pre> 00097 * 00098 * @return the difference, measured in milliseconds, between 00099 * the corrected current time and midnight, January 1, 1970 UTC. 00100 */ 00101 static int64_t safeTimeMillis(); 00102 00103 /** 00104 * Returns the last "safe" time as computed by a previous call to 00105 * the {@link #safeTimeMillis} method. 00106 * <p/> 00107 * Note: Since the underlying field is non-volatile, the returned value 00108 * is only guaranteed to be no less than the last value returned by 00109 * safeTimeMillis() call on the same thread. 00110 * 00111 * @return the last "safe" time in milliseconds 00112 */ 00113 static int64_t lastSafeTimeMillis(); 00114 00115 /** 00116 * Return the value of a system property. 00117 * 00118 * The standard naming convention for system properties is '.' 00119 * Separated property names, such as "tangosol.coherence.setting". 00120 * 00121 * As of Coherence 3.4 the only source for system properties is 00122 * environment variables. As some environemts do not allow '.' in 00123 * variable names, a failed lookup will be automatically re-issued 00124 * using a camel-cased version of the supplied name, i.e. the property 00125 * name "tangosol.coherence.setting" would translated to 00126 * "TangosolCoherenceSetting". From a code level perspective 00127 * camel-case does not need to be a consideration, it is only when 00128 * setting environment variables that it may be needed. 00129 * 00130 * @param vsName the name of the property to return 00131 * @param vsDefault the default value for the property 00132 * 00133 * @return the corresponding property value, or the supplied default if 00134 * no value could be found 00135 */ 00136 static String::View getProperty(String::View vsName, 00137 String::View vsDefault = String::null_string); 00138 00139 /** 00140 * Return the same hash code for the given object as would be returned 00141 * by the default implementation provided in Object. In the case of 00142 * NULL zero is returned. 00143 * 00144 * @param v the object to hash 00145 * 00146 * @return the object's identity hash code. 00147 */ 00148 static size32_t identityHashCode(Object::View v); 00149 00150 /** 00151 * Specify the system interrupt resolution. 00152 * 00153 * The resolution at which a blocked thread will test if it has been 00154 * interrupted. Not all blocking states are guaranteed to utilize this 00155 * feature, but at a minimum Object::wait(), and Coherence based network 00156 * communications do respect this setting. 00157 * 00158 * Once in a blocking state the blocked call may not see updates to this 00159 * setting. If this setting is to be updated it is recommended that it 00160 * only occur once at application startup. 00161 * 00162 * Recommended values are between 100 and 1000 milliseconds, default is 00163 * 250 milliseconds. 00164 * 00165 * @param cMillis the new interrupt resolution 00166 * 00167 * @throws IllegalArgumentException if cMillis <= 0 00168 */ 00169 static void setInterruptResolution(int64_t cMillis); 00170 00171 /** 00172 * Return the interrupt resolution. 00173 * 00174 * @return the interrupt resolution. 00175 */ 00176 static int64_t getInterruptResolution(); 00177 00178 /** 00179 * Load the specified library. 00180 */ 00181 static void loadLibrary(String::View vsLibName); 00182 00183 // ----- diagnostics methods -------------------------------------------- 00184 00185 public: 00186 /** 00187 * Test that the attach count on the Object is the expected value. 00188 * 00189 * This method is for testing purposes only, and will throw an 00190 * exception if the count is not the expected value. 00191 * 00192 * @param v the Object to test 00193 * @param cHandle the expected number of handles attached to this 00194 * Object 00195 * @param fEscaped the expected object escape state 00196 */ 00197 static void assertAttachCount(Object::View v, uint32_t cHandle, 00198 uint32_t cView); 00199 00200 /** 00201 * Return a string representation of the Object's life-cycle state. 00202 * 00203 * This is intended for diagnostics purposes only. 00204 * 00205 * @param v the Object to describe 00206 * 00207 * @return a human-readable description of the object's life-cycle 00208 * state 00209 */ 00210 static String::View getLifeCycleDescription(Object::View v); 00211 00212 /** 00213 * Return the System HeapAnalyzer. 00214 * 00215 * There may be only one HeapAnalyzer for the life of the process, the 00216 * default being the ObjectCountHeapAnalyzer, which is very low cost. 00217 * 00218 * The HeapAnalyzer to use may be specified via the 00219 * "tangosol.coherence.heap.analyzer" system property, can can be set 00220 * to either a registered class name, or to "none". 00221 * 00222 * If using a heap-analyzer other then the default, some Objects 00223 * created during static initialization may not be registered. 00224 * 00225 * @return the System HeapAnalyzer. 00226 */ 00227 static HeapAnalyzer::Handle getHeapAnalyzer(); 00228 00229 /** 00230 * Return the common monitor associated with the specified integer 00231 * value. 00232 * 00233 * Common monitors allow for a low-cost means to reduce contention by 00234 * spreading synchronization over a large number of monitors. An 00235 * example usage would be to produce an "atomic array". For instance 00236 * to atomically change an element within an array which is being 00237 * simultaneously updated by multiple threads: 00238 * <pre> 00239 * COH_SYNCHRONIZED (System::getCommonMonitor( 00240 * System::identityHashCode(aoShared) + i)) 00241 * { 00242 * oOld = haoShared[i]; 00243 * haoShared[i] = oNew; 00244 * } 00245 * </pre> 00246 * With this approach many threads may concurrently access various 00247 * array elements without having to synchronize on the array itself, 00248 * and contend with each other. The use of common monitors also avoids 00249 * the overhead of allocating a unique monitor per index. This example 00250 * additionally makes use of the array's identity hash code to avoid 00251 * frequent collisions against other atomic arrays for the same indices. 00252 * <p/> 00253 * As they are shared, these monitors will apply to any number of 00254 * unrelated entities, and as such certain precautions must be employed 00255 * when using them. 00256 * <ul> 00257 * <li>The holder of a common monitor MUST not synchronize on any other 00258 * common monitor. Failure to adhere to this precaution will result 00259 * in a deadlock. 00260 * <li>Notifications on a common monitor MUST use notifyAll() rather 00261 * then notify(), as there may be unrelated threads waiting for 00262 * notification on the same monitor which could consume a single 00263 * notification. Thus the only way to ensure that the desired 00264 * thread does receive notification is to notify all threads 00265 * waiting on the monitor. 00266 * <li>Threads waiting for a notification must protect themselves 00267 * against spurious style wakeups. While this is a general, though 00268 * often overlooked part of the normal use of notification, with 00269 * common monitors it is far more likely that a thread will be 00270 * notified due to an unrelated event. 00271 * <li>A thread which is holding synchronization on a common monitor 00272 * should avoid blocking operations as this could block unrelated 00273 * threads which happen to be utilizing the same common monitor. 00274 * </ul> 00275 * The ideal number of common monitors in a process is one per 00276 * concurrently executing thread. As this number is generally unknown 00277 * the default number of monitors set to a relatively high value. The 00278 * value may also be manually specified via the 00279 * <code>tangosol.coherence.commonmonitors</code> system property. 00280 * 00281 * @param i the common monitor identifier 00282 * 00283 * @return the associated monitor 00284 */ 00285 static Object::Handle getCommonMonitor(size32_t i); 00286 00287 /** 00288 * Return the common monitor associated with the specified long value. 00289 * 00290 * @param l the common monitor identifier 00291 * 00292 * @return the associated monitor 00293 * 00294 * @see #getCommonMonitor(size32_t) 00295 */ 00296 static Object::Handle getCommonMonitor(size64_t l); 00297 00298 /** 00299 * Return a random common monitor for use as the guardian of 00300 * thread-safe handles which are not a data member of a managed object. 00301 */ 00302 static Object& common(); 00303 00304 /** 00305 * Executable entrypoint for the System class. 00306 * 00307 * Print the Coherence library version information. 00308 */ 00309 static void main(ObjectArray::View); 00310 00311 00312 // ----- nested class: CommonMonitor ------------------------------------ 00313 00314 public: 00315 /** 00316 * A class which acts as CommonMonitor. 00317 * 00318 * The custom class is produced to aid in identification while profiling. 00319 */ 00320 class COH_EXPORT CommonMonitor 00321 : public class_spec<CommonMonitor> 00322 { 00323 friend class factory<CommonMonitor>; 00324 00325 protected: 00326 CommonMonitor() {} 00327 }; 00328 }; 00329 00330 COH_CLOSE_NAMESPACE2 00331 00332 #endif // COH_SYSTEM_HPP