com.bea.jvm
Interface GarbageCollector

All Superinterfaces:
Describable, JVMComponent

public interface GarbageCollector
extends JVMComponent

This interface represents the Garbage Collector of the JVM. (The GarbageCollection subsystem.)


Method Summary
 void addFinalizationListener(FinalizationListener listener)
          Add listener to be notified whenever an Object has been finalized.
 void addFinalizationListener(FinalizationListener listener, boolean onlyFailed)
          Add listener to be notified whenever an Object has been finalized.
 void addGarbageCollectionListener(GarbageCollectionListener listener)
          Adds a listener to be notified whenever a Garbage Collection run has been performed.
 void addGarbageCollectionStrategyChangeListener(GarbageCollectionStrategyChangeListener listener)
          Adds a listener for the strategy change event (@see GarbageCollectionStrategyChangeEvent).
 java.lang.String getDescription()
          A short description of the GC algorithm in use.
 java.util.Collection getGarbageCollectionStrategies()
          Returns a collection of currently available GarbageCollectionStrategies (@see GarbageCollectionStrategy).
 GarbageCollectionStrategy getGarbageCollectionStrategy()
          Returns the strategy currently being employed by the GarbageCollector.
 long getLastGCEnd()
          Returns the time the last Garbage Collection run started.
 long getLastGCStart()
          Returns the time the last Garbage Collection run started.
 long getMaxPauseTimeTarget()
           
 long getMinPauseTimeTarget()
           
 long getNurserySize()
          Returns the size of the nursery/youngspace in bytes.
 long getPauseTimeTarget()
           
 long getTotalGarbageCollectionCount()
          Returns the total number of collection runs performed so far.
 long getTotalGarbageCollectionTime()
          Returns the total time spent Garabage Collecting so far.
 boolean hasCompaction()
          Returns true if this Garbage Collector compacts the heap.
 boolean isConcurrent()
          Returns true if this Garbage Collector at some point collects garbage concurrently, i.e. in a separate thread running concurrently with the other threads.
 boolean isDynamic()
          Returns true if the GC system is running in a dynamic mode, i.e. a mode that allows the strategy to change.
 boolean isGenerational()
          Returns true if this memory model at some point uses a nursery/ young-space.
 boolean isIncremental()
          Returns true if this Garbage Collector collects garbage incrementally (in small steps, train algorithm or similar).
 boolean isParallel()
          Returns true if this Garbage Collector at some point runs in parallel on several processors when collecting garbage.
 boolean isSelfOptimizing()
          Returns true if the GC system is running in a mode that will automatically choose GarbageCollectionStrategy for you.
 void removeFinalizationListener(FinalizationListener listener)
          Removes the specified listener.
 void removeGarbageCollectionListener(GarbageCollectionListener listener)
          Removes the specified GarbageCollectionListener.
 void removeGarbageCollectionStrategyChangeListener(GarbageCollectionStrategyChangeListener listener)
          Removes a strategy change listener (@see GarbageCollectionStrategyChangeEvent).
 void setNurserySize(long nurserySize)
          Sets the nursery size.
 void setPauseTimeTarget(long target)
          Sets the pausetime target, i.e. the memory system will try its best to make sure the longest pausetime never exceeds this value.
 void suggestGarbageCollectionStrategy(GarbageCollectionStrategy strategy)
          Suggests a static garbage collector strategy to the system.
 

Method Detail

getDescription

java.lang.String getDescription()
A short description of the GC algorithm in use. For example 'Generational Concurrent', 'Parallel' etc.

Specified by:
getDescription in interface Describable
Returns:
a short description of the GC.
See Also:
Describable.getDescription()

isGenerational

boolean isGenerational()
                       throws NotAvailableException
Returns true if this memory model at some point uses a nursery/ young-space.

Returns:
true if this memory model at some point has a nursery.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

hasCompaction

boolean hasCompaction()
                      throws NotAvailableException
Returns true if this Garbage Collector compacts the heap.

Returns:
true if this memory model uses compaction.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

isIncremental

boolean isIncremental()
                      throws NotAvailableException
Returns true if this Garbage Collector collects garbage incrementally (in small steps, train algorithm or similar).

Returns:
true if this GC is incremental.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

isConcurrent

boolean isConcurrent()
                     throws NotAvailableException
Returns true if this Garbage Collector at some point collects garbage concurrently, i.e. in a separate thread running concurrently with the other threads.

Returns:
true if the mark phase or the sweep phase is concurrent.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

isParallel

boolean isParallel()
                   throws NotAvailableException
Returns true if this Garbage Collector at some point runs in parallel on several processors when collecting garbage.

Returns:
true if the mark phase or the sweep phase is parallel.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getTotalGarbageCollectionCount

long getTotalGarbageCollectionCount()
                                    throws NotAvailableException
Returns the total number of collection runs performed so far.

Returns:
the total number of GCs perfomed so far.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getLastGCStart

long getLastGCStart()
                    throws NotAvailableException
Returns the time the last Garbage Collection run started.

Returns:
the time the last GC started.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getLastGCEnd

long getLastGCEnd()
                  throws NotAvailableException
Returns the time the last Garbage Collection run started.

Returns:
the time the last GC ended.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getTotalGarbageCollectionTime

long getTotalGarbageCollectionTime()
                                   throws NotAvailableException
Returns the total time spent Garabage Collecting so far.

Returns:
total time spent in GC, in ms, so far.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getNurserySize

long getNurserySize()
                    throws NotAvailableException
Returns the size of the nursery/youngspace in bytes.

Returns:
the size of the nursery in bytes.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

setNurserySize

void setNurserySize(long nurserySize)
                    throws NotAvailableException
Sets the nursery size. The new size may not be smaller than the minimum allowed nursery size (currently 8 kB) or larger than 95% of the maximum heap size. Also the nursery size will be aligned on full pages. If a too small or too large value is given, the nursery size will be adjusted to a valid value. A non-aligned value will be aligned down to the closest page. Note that the nursery may shrink temporarily in runtime, as at most 95% of the free heap can be allocated for the nursery after an Old Garbage Collection.

Parameters:
nurserySize - the new size of the nursery.
Throws:
NotAvailableException - if the functionality isn't supported in this JVM, or if the current GarbageCollectionStrategy in use lacks a nursery (i.e. isGenerational() == false).

addGarbageCollectionListener

void addGarbageCollectionListener(GarbageCollectionListener listener)
                                  throws NotAvailableException
Adds a listener to be notified whenever a Garbage Collection run has been performed.

Parameters:
listener - the listener to use.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

removeGarbageCollectionListener

void removeGarbageCollectionListener(GarbageCollectionListener listener)
                                     throws NotAvailableException
Removes the specified GarbageCollectionListener. It will no longer be notified about GC events.

Parameters:
listener - the listener to remove.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

addFinalizationListener

void addFinalizationListener(FinalizationListener listener)
                             throws NotAvailableException
Add listener to be notified whenever an Object has been finalized.

Parameters:
listener - the listener to receive events whenever an object is finalized.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

addFinalizationListener

void addFinalizationListener(FinalizationListener listener,
                             boolean onlyFailed)
                             throws NotAvailableException
Add listener to be notified whenever an Object has been finalized.

Parameters:
listener - the listener to add.
onlyFailed - whether to only send events for finalizers that fail (i.e. throw an exception).
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

removeFinalizationListener

void removeFinalizationListener(FinalizationListener listener)
                                throws NotAvailableException
Removes the specified listener.

Parameters:
listener - the listener to remove.
Throws:
NotAvailableException - if this functionality isn't available in this JVM.

getGarbageCollectionStrategies

java.util.Collection getGarbageCollectionStrategies()
                                                    throws NotAvailableException
Returns a collection of currently available GarbageCollectionStrategies (@see GarbageCollectionStrategy). This can differ depending on the startup parameters and currently selected strategy.

Returns:
a Collection of the currently available GarbageCollectionStrategies.
Throws:
NotAvailableException - if not supported by the VM.

getGarbageCollectionStrategy

GarbageCollectionStrategy getGarbageCollectionStrategy()
                                                       throws NotAvailableException
Returns the strategy currently being employed by the GarbageCollector.

Returns:
the strategy currently being employed by the GarbageCollector.
Throws:
NotAvailableException

suggestGarbageCollectionStrategy

void suggestGarbageCollectionStrategy(GarbageCollectionStrategy strategy)
                                      throws NotAvailableException
Suggests a static garbage collector strategy to the system. You have to be in the dynamic garbage collecting mode in order to call this method. When a valid garbage collector strategy is suggested and accepted, the garbage collector will leave the self-optimizing mode but still be dynamic. (i.e. will not automatically switch garbage collector, but still possible to suggest changes to.) Suggesting the null strategy will make the collector reenter the self-optimizing mode, which in turn will make the garbage collector switch strategy automatically again.

Note that:

Parameters:
strategy - the suggested garbage collector state.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

isDynamic

boolean isDynamic()
                  throws NotAvailableException
Returns true if the GC system is running in a dynamic mode, i.e. a mode that allows the strategy to change.

Returns:
true if the GC system is running in a dynamic mode, i.e. a mode that allows the strategy to change.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

isSelfOptimizing

boolean isSelfOptimizing()
                         throws NotAvailableException
Returns true if the GC system is running in a mode that will automatically choose GarbageCollectionStrategy for you. You can force the GC system to switch to this mode by suggesting null as strategy. (@see #suggestGarbageCollectionStrategy(GarbageCollectionStrategy))

Returns:
true if the system is in a self optimizing state.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

addGarbageCollectionStrategyChangeListener

void addGarbageCollectionStrategyChangeListener(GarbageCollectionStrategyChangeListener listener)
                                                throws NotAvailableException
Adds a listener for the strategy change event (@see GarbageCollectionStrategyChangeEvent).

Parameters:
listener - the listener to add.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

removeGarbageCollectionStrategyChangeListener

void removeGarbageCollectionStrategyChangeListener(GarbageCollectionStrategyChangeListener listener)
                                                   throws NotAvailableException
Removes a strategy change listener (@see GarbageCollectionStrategyChangeEvent).

Parameters:
listener - the listener to remove.
Throws:
NotAvailableException - if this functionality isn't available in this Garbage Collector or JVM.

setPauseTimeTarget

void setPauseTimeTarget(long target)
                        throws NotAvailableException
Sets the pausetime target, i.e. the memory system will try its best to make sure the longest pausetime never exceeds this value.

Parameters:
target - the target pause time in ms.
Throws:
NotAvailableException - if the current garbage collector isn't (deterministic | gcprio:paustime).

getPauseTimeTarget

long getPauseTimeTarget()
                        throws NotAvailableException
Returns:
the current pausetime target in ms.
Throws:
NotAvailableException - if the current garbage collector isn't (deterministic | gcprio:paustime).

getMinPauseTimeTarget

long getMinPauseTimeTarget()
Returns:
the minimum possible pausetime target, or -1 if pause time target isn't available for the current GC.

getMaxPauseTimeTarget

long getMaxPauseTimeTarget()
Returns:
the maximum possible pausetime target, or -1 if pause time target isn't available for the current GC.