com.sun.rtsjx
Class FullyConcurrentGarbageCollector

java.lang.Object
  extended by javax.realtime.GarbageCollector
      extended by com.sun.rtsjx.FullyConcurrentGarbageCollector

public class FullyConcurrentGarbageCollector
extends javax.realtime.GarbageCollector

Real-Time Garbage Collector.

This is the real-time garbage collector provided with Sun Java RTS.

This class is still under development and may evolve in future versions of the product.

Please look at the product documentation for a complete description of the parameters and the variables you can access through this class.

The important point is that this collector is fully concurrent. It is based on regular threads that are scheduled like the application Java threads. They can preempt each other or run concurrently on different CPUs.

Hence, the impact of the collector on the threads depends on at which priority they run and how many processors the RTGC uses.

By default, critical threads are always more important than the RTGC and will preempt it very quickly. Non-critical real-time threads are initially more important than the RTGC. However, if they do not leave enough CPU cycles for the RTGC to complete on time, the priority of the RTGC increases to protect the critical threads. As for the java.lang.Threads, they usually run at a lower priority than the RTGC.

On multi-processor, the RTGC tries to use as many CPUs as possible. However, it can be configured to always leave a few CPUs for the applications threads, allowing them to run concurrently.

In addition to a few accessors explicitly defined, this class provides generic accessors for a lot of RTGC data, based on String identifiers. The list of parameters may evolve from one release to the other and is currently not documented.


Method Summary
static void addBlockHandler(javax.realtime.AsyncEventHandler handler)
          Add a handler to the event fired whenever threads block because the memory is exchausted.
static void addEndHandler(javax.realtime.AsyncEventHandler handler)
          Add a handler to the event fired whenever the RTGC cycle ends.
static void addPriorityHandler(javax.realtime.AsyncEventHandler handler)
          Add a handler to the event fired whenever the RTGC priority changes.
static void addStartHandler(javax.realtime.AsyncEventHandler handler)
          Add a handler to the event fired whenever the RTGC starts.
static long get(int parameterID)
          Read a parameter value.
static long get(java.lang.String parameter)
          Read a parameter value.
static int getBoostedPriority()
          Get the boosted priority of the RTGC.
 int getBoostedWorkers()
          Number of active RTGC worker threads when the RTGC is boosted.
static int getCriticalBoundary()
          Get the priority over which threads are considered critical.
static int getCriticalPriority()
          Deprecated. See BoostedPriority and CriticalBoundary
static long getCriticalReservedBytes()
          Get the amount of memory reserved for critical threads.
static int getCurrentPriority()
          Get the current priority of the RTGC.
static FullyConcurrentGarbageCollector getInstance()
          Get the single instance of this class.
static int getInvocationCount()
          Get the number of GC cycles executed.
static int getMaxCPUs()
          Deprecated. See getBoostedWorkers and getNormalWorkers.
static int getNormalPriority()
          Get the normal priority of the RTGC.
 int getNormalWorkers()
          Default number of active RTGC worker threads.
static int getParameterID(java.lang.String parameter)
          Translate a parameter to an internal ID.
 javax.realtime.RelativeTime getPreemptionLatency()
          Get the preemption latency.
static boolean isActive()
          Check whether the fully concurrent RTGC is the one managing the heap.
static void removeBlockHandler(javax.realtime.AsyncEventHandler handler)
          Remove a handler associated to the event fired whenever threads block because the memory is exchausted.
static void removeEndHandler(javax.realtime.AsyncEventHandler handler)
          Remove a handler associated to the event fired whenever the RTGC cycle ends.
static void removePriorityHandler(javax.realtime.AsyncEventHandler handler)
          Remove a handler associated to the event fired whenever the RTGC priority changes.
static void removeStartHandler(javax.realtime.AsyncEventHandler handler)
          Remove a handler associated to the event fired whenever the RTGC starts.
static boolean set(int parameterID, long value)
          Change a parameter.
static boolean set(java.lang.String parameter, long value)
          Change a parameter.
static void setBoostedPriority(int priority)
          Change the boosted priority of the RTGC.
 void setCriticalBoundary(int priority)
          Change the critical boundary.
static void setCriticalReservedBytes(long limit)
          Change the amount of memory reserved for critical threads.
 void setNormalPriority(int priority)
          Change the default priority of the RTGC.
 void setNormalWorkers(int workers)
          Change the default number of active RTGC worker threads.
static void startAsyncGC(int priority)
          Start a new RTGC cycle or boost an ongoing one.
static boolean test(java.lang.String parameter)
          Test whether a parameter exists.
static void waitThreshold(long free)
          Block the caller until the free Heap memory is below a given limit or until a RTGC cycle completes.
static void waitThreshold(long free, javax.realtime.HighResolutionTime time)
          Block the caller until the free Heap memory is below a given limit, until a timeout has expired, or until a RTGC cycle completes.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

isActive

public static boolean isActive()
Check whether the fully concurrent RTGC is the one managing the heap.

Returns:
false if the RTGC has been disabled.

getInstance

public static FullyConcurrentGarbageCollector getInstance()
Get the single instance of this class.

Returns:
the singleton, or null if the RTGC has not been activated.

getPreemptionLatency

public javax.realtime.RelativeTime getPreemptionLatency()
Get the preemption latency.

This method is part of the RTSJ specification and must be provided by this class. However, the value is not really relevant for the fully concurrent garbage collector. The preemption latency depends on the priority of the thread.

Specified by:
getPreemptionLatency in class javax.realtime.GarbageCollector
Returns:
a default value (1 millisecond)

startAsyncGC

public static void startAsyncGC(int priority)
Start a new RTGC cycle or boost an ongoing one.

This method ensures that the RTGC will run at least at the specified priority. However, the RTGC priority will not go over the BoostedPriority value. In addition, the priority cannot be lowered during a RTGC cycle. The effective priority is the maximum of the priorities explicitly requested by the user and priorities automatically computed according the RTGC scheduling policy.

Note that this method does not wait for the RTGC to complete.

Parameters:
priority - requested priority (0 to let the JVM choose the minimum).

getCurrentPriority

public static int getCurrentPriority()
Get the current priority of the RTGC.

Returns:
current priority of the RTGC.

getCriticalPriority

public static int getCriticalPriority()
Deprecated. See BoostedPriority and CriticalBoundary

Get the maximum priority of the RTGC.

Returns:
maximum priority of the RTGC.

getBoostedPriority

public static int getBoostedPriority()
Get the boosted priority of the RTGC.

Returns:
boosted priority of the RTGC.

setBoostedPriority

public static void setBoostedPriority(int priority)
Change the boosted priority of the RTGC.

The change is asynchronous and might be delayed. In addition, the RTGC might apply a slightly different value to ensure the consistency of the parameters.

Parameters:
priority - new boosted priority.

getCriticalBoundary

public static int getCriticalBoundary()
Get the priority over which threads are considered critical.

Returns:
the priority defining the critical boundary.

setCriticalBoundary

public void setCriticalBoundary(int priority)
Change the critical boundary.

Warning: if the limit is too low, the worst case memory consumption of the critical threads increases. The amount of reserved bytes must be increased.

Parameters:
priority - new limit for the critical threads

getNormalPriority

public static int getNormalPriority()
Get the normal priority of the RTGC.

Returns:
normal priority of the RTGC.

setNormalPriority

public void setNormalPriority(int priority)
Change the default priority of the RTGC.

By increasing this value, the number of important threads decreases. This improves the chances that these threads will not be preempted and will not block on allocation.

The change is asynchronous and might be delayed. In addition, the RTGC might apply a slightly different value to ensure the consistency of the parameters.

Parameters:
priority - new default priority.

getMaxCPUs

public static int getMaxCPUs()
Deprecated. See getBoostedWorkers and getNormalWorkers.

Get the maximum number of parallel threads that the RTGC can use.

With the current implementation, this is a constant depending only on command line options. It corresponds the number of worker threads when the RTGC is boosted.

Returns:
maximum number of parallel threads that the RTGC can use.

getBoostedWorkers

public int getBoostedWorkers()
Number of active RTGC worker threads when the RTGC is boosted.

Returns:
the active RTGC worker threads when the RTGC is boosted.

getNormalWorkers

public int getNormalWorkers()
Default number of active RTGC worker threads.

Returns:
the default number of active RTGC threads.

setNormalWorkers

public void setNormalWorkers(int workers)
Change the default number of active RTGC worker threads.

By decreasing this value, threads running at a priority lower than NormalPriority will get more CPU cycles when the RTGC need not be boosted. The trade-off is that the RTGC may have to be boosted more often, thus impacting the important threads.

Parameters:
workers - new default number of active RTGC worker threads.

getCriticalReservedBytes

public static long getCriticalReservedBytes()
Get the amount of memory reserved for critical threads.

Returns:
amount of memory reserved for critical threads.

setCriticalReservedBytes

public static void setCriticalReservedBytes(long limit)
Change the amount of memory reserved for critical threads.

If the new limit is too low, critical threads may block when the memory is exhausted. If too high, the other threads will block more often.

Parameters:
limit - amount of memory reserved for critical threads.

addStartHandler

public static void addStartHandler(javax.realtime.AsyncEventHandler handler)
Add a handler to the event fired whenever the RTGC starts.

Parameters:
handler - The handler added if it it not yet associated to the event

removeStartHandler

public static void removeStartHandler(javax.realtime.AsyncEventHandler handler)
Remove a handler associated to the event fired whenever the RTGC starts.

Parameters:
handler - The handler to remove if it is associated to the event.

addPriorityHandler

public static void addPriorityHandler(javax.realtime.AsyncEventHandler handler)
Add a handler to the event fired whenever the RTGC priority changes.

Parameters:
handler - The handler added if it it not yet associated to the event

removePriorityHandler

public static void removePriorityHandler(javax.realtime.AsyncEventHandler handler)
Remove a handler associated to the event fired whenever the RTGC priority changes.

Parameters:
handler - The handler to remove if it is associated to the event.

addEndHandler

public static void addEndHandler(javax.realtime.AsyncEventHandler handler)
Add a handler to the event fired whenever the RTGC cycle ends.

Parameters:
handler - The handler added if it it not yet associated to the event

removeEndHandler

public static void removeEndHandler(javax.realtime.AsyncEventHandler handler)
Remove a handler associated to the event fired whenever the RTGC cycle ends.

Parameters:
handler - The handler to remove if it is associated to the event.

addBlockHandler

public static void addBlockHandler(javax.realtime.AsyncEventHandler handler)
Add a handler to the event fired whenever threads block because the memory is exchausted.

Parameters:
handler - The handler added if it it not yet associated to the event

removeBlockHandler

public static void removeBlockHandler(javax.realtime.AsyncEventHandler handler)
Remove a handler associated to the event fired whenever threads block because the memory is exchausted.

Parameters:
handler - The handler to remove if it is associated to the event.

waitThreshold

public static void waitThreshold(long free)
Block the caller until the free Heap memory is below a given limit or until a RTGC cycle completes.

Parameters:
free - heap memory limit, in bytes.

waitThreshold

public static void waitThreshold(long free,
                                 javax.realtime.HighResolutionTime time)
Block the caller until the free Heap memory is below a given limit, until a timeout has expired, or until a RTGC cycle completes.

Parameters:
free - heap memory limit, in bytes.
time - timeout, infinite if NULL.

getInvocationCount

public static int getInvocationCount()
Get the number of GC cycles executed.

Returns:
number of GC cycles executed.

test

public static boolean test(java.lang.String parameter)
Test whether a parameter exists. This method will improve portability. The current list of attributes is not documented because it will probably evolve from one release to the other and should not be used directly by user code. This method will ensure that user code that depends on these extended attributes can check that they still exist in future releases.

Parameters:
parameter - parameter name
Returns:
whether the parameter exists

set

public static boolean set(java.lang.String parameter,
                          long value)
Change a parameter. The change is ignored if the parameter does not exists.

Parameters:
parameter - parameter name
value - new value
Returns:
whether the parameter exists

get

public static long get(java.lang.String parameter)
Read a parameter value. 0 is returned if the parameter does not exist.

Parameters:
parameter - parameter name
Returns:
the value, encoded as a long, or 0 if the parameter is not recognized.

getParameterID

public static int getParameterID(java.lang.String parameter)
Translate a parameter to an internal ID.

Parameters:
parameter - parameter name
Returns:
the indentifier for the parameter, or 0 if it does not exist.

set

public static boolean set(int parameterID,
                          long value)
Change a parameter. The change is silently ignored if the parameter does not exists.

Parameters:
parameterID - identifier for the parameter
value - new value, expressed as a long
Returns:
whether the parameter exists

get

public static long get(int parameterID)
Read a parameter value. 0 is returned if the parameter does not exist.

Parameters:
parameterID - identifier for the parameter
Returns:
the parameter value, converted to long