PIRL.Viewers
Class Memory_History

java.lang.Object
  PIRL.Viewers.Memory_History

public class Memory_History
extends Object

A Memory_History provides a history of Java Runtime Environment (JRE) memory use.

The JRE reports three categories of memory: the total amount of available memory in the JRE heap space, the amount of allocated memory used by objects, and the amount of free memory that is no longer in use by objects which can be garbage collected.

Field Summary

protected long[]	Allocated The allocated memory sampling history.
static int	DEFAULT_MAX_SAMPLES The
protected long[]	Free The free memory sampling history.
static String	ID Class identification name with source code version and date.
protected int	Samples

Constructor Summary

Memory_History()
Constructs an idle Memory_History with DEFAULT_MAX_SAMPLES sample capacity.

Memory_History(int max_samples, int rate)
Constructs at Memory_History with specified max samples and sampling rate.

Method Summary

void	addChangeListener(ChangeListener listener) Register a ChangeListener.
long[]	Allocated_History() Get allocated memory samples history.
static long	Allocated_Memory() Get the amount of memory currently in use by the Java runtime environment.
static long	Available_Memory() Get the total amount of memory available to the Java runtime environment.
protected void	Clear() Clear the memory history.
protected void	fireChange() Send a ChangeEvent referencing this Memory_History to each registered ChangeListener.
long[]	Free_History() Get free memory samples history.
static long	Free_Memory() Get the amount of memory allocated by the Java runtime environment but not currently in use.
protected void	Historical(long free, long allocated) Add values to the memory history.
long[][]	History() Get the memory samples history.
int	Max_Samples() Get the maximum number of history samples that can be recorded.
void	Max_Samples(int max_samples) Set the maximum number of history samples that can be recorded.
int	Previous_Rate() Get the previous sampling rate.
int	Rate() Get the rate at which memory usage is being sampled.
int	Rate(int rate) Set the rate at which to sample memory usage.
boolean	removeChangeListener(ChangeListener listener) Remove a registered ChangeListener.
void	Reset() The memory history is emptied.
int	Samples() Get the count of valid memory history samples.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ID

public static final String ID

Class identification name with source code version and date.

See Also:

Constant Field Values

DEFAULT_MAX_SAMPLES

public static final int DEFAULT_MAX_SAMPLES

The

See Also:

Constant Field Values

Samples

protected int Samples

Free

protected long[] Free

The free memory sampling history.

Allocated

protected long[] Allocated

The allocated memory sampling history.

Constructor Detail

Memory_History

public Memory_History(int max_samples,
                      int rate)

Constructs at Memory_History with specified max samples and sampling rate.

Parameters:

max_samples - The maximum number of JRE memory use samples to acquire.

rate - The rate, in seconds, between memory samples.

Memory_History

public Memory_History()

Constructs an idle Memory_History with DEFAULT_MAX_SAMPLES sample capacity.

The Memory_History will have no history capacity and a memory sampling will be disabled.

Method Detail

Free_Memory

public static long Free_Memory()

Get the amount of memory allocated by the Java runtime environment but not currently in use.

Free memory is part of the allocated memory pool but is not currently in use. Garbage collection frees memory.

Returns:

The amount, in bytes, of allocated but free memory.

See Also:

Runtime.freeMemory()

Allocated_Memory

public static long Allocated_Memory()

Get the amount of memory currently in use by the Java runtime environment.

Allocated memory is taken from the total amount of memory made available to the Java runtime environment when the Java virtual machine is started. Memory that is allocated, but not free is currently in use by the virtual machine, including any user objects it is managing.

Returns:

The amount, in bytes, of allocated memory.

See Also:

Available_Memory(), Runtime.totalMemory()

Available_Memory

public static long Available_Memory()

Get the total amount of memory available to the Java runtime environment.

When the Java virtual machine is started some amount of the host system memory is reserved for use by the Java runtime environment. allocated memory is taken from available memory when needed. The default amount of available memory can be changed using the java -Xmx command line option.

Returns:

The total amount of memory, in bytes, available to the Java runtime environment.

See Also:

Runtime.maxMemory()

Rate

public int Rate()

Get the rate at which memory usage is being sampled.

Returns:

The sampling rate in seconds. This will be zero if sampling is not active.

See Also:

Rate(int), Previous_Rate()

Rate

public int Rate(int rate)

Set the rate at which to sample memory usage.

If the current sampling rate is the same as the new sampling rate, nothing is done.

If the new sampling rate is less than or equal to zero the sampling timer is stopped.

If the new sampling rate is positive a samping timer will be constructed if one has not already been provided; otherwise the current sampling history will be cleared. If the sampling timer is not already running it will be started. The sampling timer's action event will updated the memory history at the specified rate, and will continue to be updated at the same rate until sampling is discontinued by setting the rate at or below zero. The sampling rate may be changed while sampling is active.

The intention is to have a sample at each rate point in time. However, the timer can not guarantee this: Other activity on the system may prevent the timer from generating an event at the requested time. Nevertheless, by preventing events from being coalesced there will still be the correct number of events generated for the overall amount of elapsed time even though the burst of catch-up events will result in memory values not being sampled at the expected time; no sampling events will be dropped.

After the sampling rate has been changed a ChangeEvent is fired.

Parameters:

rate - The rate, in seconds, between each memory usage sample. If less than or equal to zero sampling will be discontinued.

Returns:

The previous sampling rate. If this value is not zero the previous rate will be recorded.

Previous_Rate

public int Previous_Rate()

Get the previous sampling rate.

The value returned is the previous non-zero sampling rate that was used. However, if sampling was never enabled then this will be zero.

Returns:

The previous non-zero sampling rate, or zero if sampling was never enabled.

See Also:

Rate()

Historical

protected void Historical(long free,
                          long allocated)

Add values to the memory history.

If the history capacity has not been reached the valid samples count is incremented. All the current allocated and free memory sample values are shifted down in their arrays and then the new values are set as the current (index zero) entries.

It might be argued that new sample values should be added to the end of the history arrays rather than at the beginning. However, once the history capacity has been reached the array contents would need to be shifted anyway. It is conceptually and programatically easier to work with the history arrays if the most recent sample is first.

Parameters:

free - The new free memory sample value.

allocated - The new allocated memory sample value.

See Also:

Allocated_History(), Free_History()

Samples

public int Samples()

Get the count of valid memory history samples.

Returns:

The number of valid memory history samples that are available.

See Also:

Allocated_History(), Free_History()

Max_Samples

public int Max_Samples()

Get the maximum number of history samples that can be recorded.

Returns:

The maximum number of history samples that will be recorded.

See Also:

Allocated_History(), Free_History()

Max_Samples

public void Max_Samples(int max_samples)

Set the maximum number of history samples that can be recorded.

If the new sample capacity is different from the current sample capacity new sample history arrays are allocated and the previous valid sample values, up to the current sample count or the new capacity (whichever is smaller), are copied into the new history arrays. Then the new history arrays are set as the current history arrays.

After the history arrays have been changed a ChangeEvent is fired.

Parameters:

max_samples - The memory history sample capacity. If the value is less than or equal to zero the DEFAULT_MAX_SAMPLES will be used.

Reset

public void Reset()

The memory history is emptied.

After the memory history has been reset a ChangeEvent is fired.

See Also:

Clear()

Clear

protected void Clear()

Clear the memory history.

The memory sample history array values and the count of valid samples are set to zero.

See Also:

Samples(), Allocated_History(), Free_History()

Free_History

public long[] Free_History()

Get free memory samples history.

Returns:

An array of long values that contain the history of free memory samples. This array will have as many entries as the samples count.

Allocated_History

public long[] Allocated_History()

Get allocated memory samples history.

Returns:

An array of long values that contain the history of allocated memory samples. This array will have as many entries as the samples count.

History

public long[][] History()

Get the memory samples history.

Returns:

An array of long value pairs that contain the history of allocated memory samples in the first value of the pair (array[i][0] and free memory samples in the second value of the pair (array[i][1]). This array will have as many sample value pair entries as the samples count.

addChangeListener

public void addChangeListener(ChangeListener listener)

Register a ChangeListener.

Parameters:

listener - The ChangeListener to be added to the list registered for this Memory_History. The listener is not added if it is already registered..

removeChangeListener

public boolean removeChangeListener(ChangeListener listener)

Remove a registered ChangeListener.

Parameters:

listener - The ChangeListener to be removed.

fireChange

protected void fireChange()

Send a ChangeEvent referencing this Memory_History to each registered ChangeListener.

See Also:

addChangeListener(ChangeListener)