Oracle Fusion Middleware C++ API Reference for Oracle Coherence: System Class Reference

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 holder of a common monitor MUST not synchronize on any other common monitor. Failure to adhere to this precaution will result in a deadlock.
Notifications on a common monitor MUST use notifyAll() rather then notify(), as there may be unrelated threads waiting for notification on the same monitor which could consume a single notification. Thus the only way to ensure that the desired thread does receive notification is to notify all threads waiting on the monitor.
Threads waiting for a notification must protect themselves against spurious style wakeups. While this is a general, though often overlooked part of the normal use of notification, with common monitors it is far more likely that a thread will be notified due to an unrelated event.
A thread which is holding synchronization on a common monitor should avoid blocking operations as this could block unrelated threads which happen to be utilizing the same common monitor.

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.

System Class Reference

Detailed Description

Public Types

Static Public Member Functions

Classes

Member Function Documentation


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 Object &	common ()
	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...