Oracle Coherence for C++ API
Release 3.7.0.0

E18684-01

coherence/lang/System.hpp

00001 /*
00002 * System.hpp
00003 *
00004 * Copyright (c) 2000, 2011, 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
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.