javax.realtime
Class MemoryParameters

java.lang.Object
  extended by javax.realtime.MemoryParameters
All Implemented Interfaces:
java.lang.Cloneable

public class MemoryParameters
extends java.lang.Object
implements java.lang.Cloneable

Memory parameters can be given on the constructor of RealtimeThread and AsyncEventHandler. These can be used both for the purposes of admission control by the scheduler and for the purposes of pacing the garbage collector (if any) to satisfy all of the schedulable object memory allocation rates.

The limits in a MemoryParameters instance are enforced when a schedulable object creates a new object, e.g., uses the new operation. When a schedulable object exceeds its allocation or allocation rate limit, the error is handled as if the allocation failed because of insufficient memory. The object allocation throws an OutOfMemoryError.

When a reference to a MemoryParameters object is given as a parameter to a constructor, the MemoryParameters object becomes bound to the object being created. Changes to the values in the MemoryParameters object affect the constructed object. If given to more than one constructor, then changes to the values in the MemoryParameters object affect all of the associated objects. Note that this is a one-to-many relationship and not a many-to-many.

A MemoryParameters object may be shared, but that does not cause the memory budgets reflected by the parameter to be shared among the schedulable objects that are associated with the parameter object.

Caution: This class is explicitly unsafe in multithreaded situations when it is being changed. No synchronization is done. It is assumed that users of this class who are mutating instances will be doing their own synchronization at a higher level.


Field Summary
static long NO_MAX
          Specifies no maximum limit.
 
Constructor Summary
MemoryParameters(long maxMemoryArea, long maxImmortal)
          Create a MemoryParameters object with the given values.
MemoryParameters(long maxMemoryArea, long maxImmortal, long allocationRate)
          Create a MemoryParameters object with the given values.
 
Method Summary
 java.lang.Object clone()
          Return a clone of this.
 long getAllocationRate()
          Gets the limit on the rate of allocation in the heap.
 long getMaxImmortal()
          Gets the limit on the amount of memory the schedulable object may allocate in the immortal area.
 long getMaxMemoryArea()
          Gets the limit on the amount of memory the schedulable object may allocate in its initial memory area.
 void setAllocationRate(long allocationRate)
          Sets the limit on the rate of allocation in the heap.
 boolean setAllocationRateIfFeasible(long allocationRate)
          Sets the limit on the rate of allocation in the heap.
 boolean setMaxImmortalIfFeasible(long maximum)
          Sets the limit on the amount of memory the schedulable object may allocate in the immortal area.
 boolean setMaxMemoryAreaIfFeasible(long maximum)
          Sets the limit on the amount of memory the schedulable object may allocate in its initial memory area.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NO_MAX

public static final long NO_MAX
Specifies no maximum limit.

See Also:
Constant Field Values
Constructor Detail

MemoryParameters

public MemoryParameters(long maxMemoryArea,
                        long maxImmortal)
Create a MemoryParameters object with the given values.

Parameters:
maxMemoryArea - A limit on the amount of memory the schedulable object may allocate in its initial memory area. Units are in bytes. If zero, no allocation allowed in the memory area. To specify no limit, use NO_MAX.
maxImmortal - A limit on the amount of memory the schedulable object may allocate in the immortal area. Units are in bytes. If zero, no allocation allowed in immortal. To specify no limit, use NO_MAX.
Throws:
java.lang.IllegalArgumentException - Thrown if any value other than positive. zero, or NO_MAX is passed as the value of maxMemoryArea or maxImmortal.

MemoryParameters

public MemoryParameters(long maxMemoryArea,
                        long maxImmortal,
                        long allocationRate)
Create a MemoryParameters object with the given values.

Parameters:
maxMemoryArea - A limit on the amount of memory the schedulable object may allocate in its initial memory area. Units are in bytes. If zero, no allocation allowed in the memory area. To specify no limit, use NO_MAX.
maxImmortal - A limit on the amount of memory the schedulable object may allocate in the immortal area. Units are in bytes. If zero, no allocation allowed in immortal. To specify no limit, use NO_MAX.
allocationRate - A limit on the rate of allocation in the heap. Units are in bytes per second of wall clock time. If allocationRate is zero, no allocation is allowed in the heap. To specify no limit, use NO_MAX. Measurement starts when the schedulable object is first released for execution (not when it is constructed.) Enforcement of the allocation rate is an implementation option. If the implementation does not enforce allocation rate limits, it treats all non-zero allocation rate limits as NO_MAX.
Throws:
java.lang.IllegalArgumentException - Thrown if any value other than positive. zero, or NO_MAX is passed as the value of maxMemoryArea or maxImmortal, or allocationRate.
Method Detail

clone

public java.lang.Object clone()
Return a clone of this. This method should behave effectively as if it constructed a new object with the visible values of this.

Overrides:
clone in class java.lang.Object
Since:
1.0.1

getAllocationRate

public long getAllocationRate()
Gets the limit on the rate of allocation in the heap. Units are in bytes per second.

Returns:
The allocation rate in bytes per second. If zero, no allocation is allowed in the heap. If the returned value is NO_MAX then the allocation rate on the heap is uncontrolled.

getMaxImmortal

public long getMaxImmortal()
Gets the limit on the amount of memory the schedulable object may allocate in the immortal area. Units are in bytes.

Returns:
The limit on immortal memory allocation. If zero, no allocation is allowed in immortal memory. If the returned value is NO_MAX then there is no limit for allocation in immortal memory.

getMaxMemoryArea

public long getMaxMemoryArea()
Gets the limit on the amount of memory the schedulable object may allocate in its initial memory area. Units are in bytes.

Returns:
The allocation limit in the schedulable object's initial memory area. If zero, no allocation is allowed in the initial memory area. If the returned value is NO_MAX then there is no limit for allocation in the initial memory area.

setAllocationRate

public void setAllocationRate(long allocationRate)
Sets the limit on the rate of allocation in the heap.

Parameters:
allocationRate - Units are in bytes per second of wall-clock time. If allocationRate is zero, no allocation is allowed in the heap. To specify no limit, use NO_MAX. Measurement starts when the schedulable object starts (not when it is constructed.) Enforcement of the allocation rate is an implementation option. If the implementation does not enforce allocation rate limits, it treats all non-zero allocation rate limits as NO_MAX.
Throws:
java.lang.IllegalArgumentException - Thrown if any value other than positive, zero, or NO_MAX is passed as the value of allocationRate.

setAllocationRateIfFeasible

public boolean setAllocationRateIfFeasible(long allocationRate)
Sets the limit on the rate of allocation in the heap. If this MemoryParameters object is currently associated with one or more schedulable objects that have been passed admission control, this change in allocation rate will be submitted to admission control. The scheduler (in conjunction with the garbage collector) will either admit all the effected threads with the new allocation rate, or leave the allocation rate unchanged and cause setAllocationRateIfFeasible to return false.

Parameters:
allocationRate - Units are in bytes per second of wall-clock time. If allocationRate is zero, no allocation is allowed in the heap. To specify no limit, use NO_MAX. Enforcement of the allocation rate is an implementation option. If the implementation does not enforce allocation rate limits, it treats all non-zero allocation rate limits as NO_MAX.
Returns:
True if the request was fulfilled.
Throws:
java.lang.IllegalArgumentException - Thrown if any value other than positive, zero, or NO_MAX is passed as the value of allocationRate.

setMaxImmortalIfFeasible

public boolean setMaxImmortalIfFeasible(long maximum)
Sets the limit on the amount of memory the schedulable object may allocate in the immortal area.

Parameters:
maximum - Units are in bytes. If zero, no allocation allowed in immortal. To specify no limit, use NO_MAX.
Returns:
True if the value is set. False if any of the schedulable objects have already allocated more than the given value. In this case the call has no effect.
Throws:
java.lang.IllegalArgumentException - Thrown if any value other than positive, zero, or NO_MAX is passed as the value of maximum.

setMaxMemoryAreaIfFeasible

public boolean setMaxMemoryAreaIfFeasible(long maximum)
Sets the limit on the amount of memory the schedulable object may allocate in its initial memory area.

Parameters:
maximum - Units are in bytes. If zero, no allocation allowed in the initial memory area. To specify no limit, use NO_MAX.
Returns:
True if the value is set. False if any of the schedulable objects have already allocated more than the given value. In this case the call has no effect.
Throws:
java.lang.IllegalArgumentException - Thrown if any value other than positive, zero, or NO_MAX is passed as the value of maximum.