Oracle Coherence for C++ API
Release 3.7.0.0

E18684-01

System Class Reference

#include <coherence/lang/System.hpp>

Inherits Object.

List of all members.


Detailed Description

A collection of general purpose utility methods.

Author:
mf 2007.12.19

Public Types

typedef spec::Handle Handle
 System Handle definition.
typedef spec::View View
 System View definition.
typedef spec::Holder Holder
 System Holder definition.

Static Public Member Functions

static void gc (bool fFull=false)
 Runs the garbage collector.
static int64_t upTimeMillis ()
 Return the number of milliseconds which have elapsed since the process was started.
static int64_t currentTimeMillis ()
 Return the elapsed milliseconds since midnight January 1, 1970 UTC.
static int64_t safeTimeMillis ()
 Returns a "safe" current time in milliseconds.
static int64_t lastSafeTimeMillis ()
 Returns the last "safe" time as computed by a previous call to the safeTimeMillis method.
static String::View getProperty (String::View vsName, String::View vsDefault=String::null_string)
 Return the value of a system property.
static size32_t identityHashCode (Object::View v)
 Return the same hash code for the given object as would be returned by the default implementation provided in Object.
static void setInterruptResolution (int64_t cMillis)
 Specify the system interrupt resolution.
static int64_t getInterruptResolution ()
 Return the interrupt resolution.
static void loadLibrary (String::View vsLibName)
 Load the specified library.
static void assertAttachCount (Object::View v, uint32_t cHandle, uint32_t cView)
 Test that the attach count on the Object is the expected value.
static String::View getLifeCycleDescription (Object::View v)
 Return a string representation of the Object's life-cycle state.
static
HeapAnalyzer::Handle 
getHeapAnalyzer ()
 Return the System HeapAnalyzer.
static Object::Handle getCommonMonitor (size32_t i)
 Return the common monitor associated with the specified integer value.
static Object::Handle getCommonMonitor (size64_t l)
 Return the common monitor associated with the specified long value.
static Objectcommon ()
 Return a random common monitor for use as the guardian of thread-safe handles which are not a data member of a managed object.
static void main (ObjectArray::View)
 Executable entrypoint for the System class.

Classes

class  CommonMonitor
 A class which acts as CommonMonitor. More...

Member Function Documentation

static void gc ( bool  fFull = false  )  [static]

Runs the garbage collector.

While most managed objects are automatically reclaimed when their reference count reaches zero, some special case objects utilize deferred automatic cleanup. Calling this method will expedite this deferred cleanup.

Parameters:
fFull true iff an exhaustive collection is desired

static int64_t upTimeMillis (  )  [static]

Return the number of milliseconds which have elapsed since the process was started.

Returns:
the number of milliseconds which have elapsed since the process was started

static int64_t currentTimeMillis (  )  [static]

Return the elapsed milliseconds since midnight January 1, 1970 UTC.

This function does not guard against the clock rolling back or jumping forward.

Returns:
the elapsed milliseconds

static int64_t safeTimeMillis (  )  [static]

Returns a "safe" current time in milliseconds.

Unlike the currentTimeMillis() this method guarantees that the time never "goes back".

More specifically, when called twice on the same thread, the second call will never return a value that is less then the value returned by the first call. If a system time correction becomes necessary, an attempt will be made to gradually compensate the returned value, so in the long run the value returned by this method is the same as the system time.

Additionally, the following always holds true:

   System::safeTimeMillis() >= System::currentTimeMillis();
 

Returns:
the difference, measured in milliseconds, between the corrected current time and midnight, January 1, 1970 UTC.

static int64_t lastSafeTimeMillis (  )  [static]

Returns the last "safe" time as computed by a previous call to the safeTimeMillis method.

Note: Since the underlying field is non-volatile, the returned value is only guaranteed to be no less than the last value returned by safeTimeMillis() call on the same thread.

Returns:
the last "safe" time in milliseconds

static String::View getProperty ( String::View  vsName,
String::View  vsDefault = String::null_string 
) [static]

Return the value of a system property.

The standard naming convention for system properties is '.' Separated property names, such as "tangosol.coherence.setting".

As of Coherence 3.4 the only source for system properties is environment variables. As some environemts do not allow '.' in variable names, a failed lookup will be automatically re-issued using a camel-cased version of the supplied name, i.e. the property name "tangosol.coherence.setting" would translated to "TangosolCoherenceSetting". From a code level perspective camel-case does not need to be a consideration, it is only when setting environment variables that it may be needed.

Parameters:
vsName the name of the property to return
vsDefault the default value for the property
Returns:
the corresponding property value, or the supplied default if no value could be found

static size32_t identityHashCode ( Object::View  v  )  [static]

Return the same hash code for the given object as would be returned by the default implementation provided in Object.

In the case of NULL zero is returned.

Parameters:
v the object to hash
Returns:
the object's identity hash code.

static void setInterruptResolution ( int64_t  cMillis  )  [static]

Specify the system interrupt resolution.

The resolution at which a blocked thread will test if it has been interrupted. Not all blocking states are guaranteed to utilize this feature, but at a minimum Object::wait(), and Coherence based network communications do respect this setting.

Once in a blocking state the blocked call may not see updates to this setting. If this setting is to be updated it is recommended that it only occur once at application startup.

Recommended values are between 100 and 1000 milliseconds, default is 250 milliseconds.

Parameters:
cMillis the new interrupt resolution
Exceptions:
IllegalArgumentException if cMillis <= 0

static int64_t getInterruptResolution (  )  [static]

Return the interrupt resolution.

Returns:
the interrupt resolution.

static void assertAttachCount ( Object::View  v,
uint32_t  cHandle,
uint32_t  cView 
) [static]

Test that the attach count on the Object is the expected value.

This method is for testing purposes only, and will throw an exception if the count is not the expected value.

Parameters:
v the Object to test
cHandle the expected number of handles attached to this Object
fEscaped the expected object escape state

static String::View getLifeCycleDescription ( Object::View  v  )  [static]

Return a string representation of the Object's life-cycle state.

This is intended for diagnostics purposes only.

Parameters:
v the Object to describe
Returns:
a human-readable description of the object's life-cycle state

static HeapAnalyzer::Handle getHeapAnalyzer (  )  [static]

Return the System HeapAnalyzer.

There may be only one HeapAnalyzer for the life of the process, the default being the ObjectCountHeapAnalyzer, which is very low cost.

The HeapAnalyzer to use may be specified via the "tangosol.coherence.heap.analyzer" system property, can can be set to either a registered class name, or to "none".

If using a heap-analyzer other then the default, some Objects created during static initialization may not be registered.

Returns:
the System HeapAnalyzer.

static Object::Handle getCommonMonitor ( size32_t  i  )  [static]

Return the common monitor associated with the specified integer value.

Common monitors allow for a low-cost means to reduce contention by spreading synchronization over a large number of monitors. An example usage would be to produce an "atomic array". For instance to atomically change an element within an array which is being simultaneously updated by multiple threads:

 COH_SYNCHRONIZED (System::getCommonMonitor(
   System::identityHashCode(aoShared) + i))
     {
     oOld = haoShared[i];
     haoShared[i] = oNew;
     }
 
With this approach many threads may concurrently access various array elements without having to synchronize on the array itself, and contend with each other. The use of common monitors also avoids the overhead of allocating a unique monitor per index. This example additionally makes use of the array's identity hash code to avoid frequent collisions against other atomic arrays for the same indices.

As they are shared, these monitors will apply to any number of unrelated entities, and as such certain precautions must be employed when using them.

The ideal number of common monitors in a process is one per concurrently executing thread. As this number is generally unknown the default number of monitors set to a relatively high value. The value may also be manually specified via the tangosol.coherence.commonmonitors system property.

Parameters:
i the common monitor identifier
Returns:
the associated monitor

static Object::Handle getCommonMonitor ( size64_t  l  )  [static]

Return the common monitor associated with the specified long value.

Parameters:
l the common monitor identifier
Returns:
the associated monitor
See also:
getCommonMonitor(size32_t)

static void main ( ObjectArray::View   )  [static]

Executable entrypoint for the System class.

Print the Coherence library version information.


The documentation for this class was generated from the following file:
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.