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

Fields
`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

Constructors
Constructor and Description
`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

Methods
`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)`