javax.realtime

Class MemoryParameters

java.lang.Object

javax.realtime.MemoryParameters

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

ScopedMemoryParameters

public class MemoryParameters
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

Memory parameters can be given on the constructor of any Schedulable. They provide limits on allocation. For garbage-collected objects, they provide the rate of allocation, and for Immortal, the overall amount of allocation.

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

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

As of RTSJ 2.0, instances of MemoryParameters are immutable.

See Also:

Serialized Form

Caution: This class is explicitly unsafe for multithreading when being changed. Code that mutates instances of this class should synchronize at a higher level.

Field Summary

Fields

Modifier and Type	Field and Description
static long	NO_MAX Deprecated. since RTSJ 2.0.
static long	UNLIMITED Specifies no maximum limit.

Constructor Summary

Constructors

Constructor and Description
MemoryParameters(long allocationRate) Creates a MemoryParameters object with the given values and allocationRate set to allocationRate.
MemoryParameters(long maxInitialArea, long maxImmortal) Creates a MemoryParameters object with the given values and allocationRate set to UNLIMITED.
MemoryParameters(long maxInitialArea, long maxImmortal, long allocationRate) Creates a MemoryParameters object with the given values.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Returns a clone of this.
long	getAllocationRate() Determines the limit on the rate of allocation in the heap.
long	getMaxImmortal() Gets the limit on the amount of memory the schedulable may allocate in the immortal area.
long	getMaxInitialMemoryArea() Gets the limit on the amount of memory the schedulable may allocate in its initial memory area, when initial is a scoped memory.
long	getMaxMemoryArea() Deprecated. since RTSJ 2.0, repleace by getMaxInitialMemoryArea.
void	setAllocationRate(long allocationRate) Deprecated. RTSJ 2.0
boolean	setAllocationRateIfFeasible(long allocationRate) Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate.
boolean	setMaxImmortalIfFeasible(long maximum) Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate
boolean	setMaxMemoryAreaIfFeasible(long maximum) Deprecated. as of RTSJ 2.0, since the framework for feasibility analysis is inadequate.

Methods inherited from class java.lang.Object

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

Field Detail

UNLIMITED

public static final long UNLIMITED

Specifies no maximum limit.

Since:

RTSJ 2.0

See Also:

Constant Field Values

NO_MAX

@Deprecated
public static final long NO_MAX

Deprecated. since RTSJ 2.0.

Specifies no maximum limit.

See Also:

Constant Field Values

Constructor Detail

MemoryParameters

public MemoryParameters(long maxInitialArea,
                        long maxImmortal,
                        long allocationRate)
                 throws StaticIllegalArgumentException

Creates a MemoryParameters object with the given values.

Parameters:

maxInitialArea - A limit on the amount of memory the schedulable may allocate in its initial scoped memory area. Units are in bytes. When zero, no allocation is allowed in the memory area. When the initial memory area is not a ScopedMemory, this parameter has no effect. To specify no limit, use UNLIMITED.

maxImmortal - A limit on the amount of memory the schedulable may allocate in the immortal area. Units are in bytes. When zero, no allocation is allowed in immortal. To specify no limit, use UNLIMITED.

allocationRate - A limit on the rate of allocation in the heap. Units are in bytes per second of wall clock time. When allocationRate is zero, no allocation is allowed in the heap. To specify no limit, use UNLIMITED. Measurement starts when the schedulable is first released for execution; not when it is constructed. Enforcement of the allocation rate is an implementation option. When the implementation does not enforce allocation rate limits, it treats all positive allocation rate limits as UNLIMITED.

Throws:

StaticIllegalArgumentException - when any value less than zero is passed as the value of maxInitialArea, maxImmortal, or allocationRate.

MemoryParameters

public MemoryParameters(long maxInitialArea,
                        long maxImmortal)

Creates a MemoryParameters object with the given values and allocationRate set to UNLIMITED. It has the same effect as MemoryParameters(maxInitialArea, maxImmortal, UNLIMITED)

MemoryParameters

public MemoryParameters(long allocationRate)

Creates a MemoryParameters object with the given values and allocationRate set to allocationRate. It has the same effect as MemoryParameters(UNLIMITED, UNLIMITED, allocationRate)

Since:

RTSJ 2.0

Method Detail

clone

public java.lang.Object clone()

Returns a clone of this. This method should behave effectively as if it constructed a new object with the visible values of this.

• The new object is in the current allocation context.
• clone does not copy any associations from this and it does not implicitly bind the new object to a SO.

Overrides:

clone in class java.lang.Object

Since:

RTSJ 1.0.1

getAllocationRate

public long getAllocationRate()

Determines the limit on the rate of allocation in the heap. Units are in bytes per second.

Returns:

the allocation rate in bytes per second. When zero, no allocation is allowed in the heap. When the returned value is UNLIMITED then the allocation rate on the heap is uncontrolled. Enforcement of allocation rates between zero and UNLIMITED is implementation dependent.

getMaxImmortal

public long getMaxImmortal()

Gets the limit on the amount of memory the schedulable may allocate in the immortal area. Units are in bytes.

Returns:

the limit on immortal memory allocation. When zero, no allocation is allowed in immortal memory. When the returned value is UNLIMITED then there is no limit for allocation in immortal memory.

getMaxInitialMemoryArea

public long getMaxInitialMemoryArea()

Gets the limit on the amount of memory the schedulable may allocate in its initial memory area, when initial is a scoped memory. Units are in bytes.

Returns:

the allocation limit in the schedulable's initial memory area. When zero, no allocation is allowed in the initial memory area. When the returned value is UNLIMITED then there is no limit for allocation in the initial memory area.

Since:

RTSJ 2.0

getMaxMemoryArea

@Deprecated
public long getMaxMemoryArea()

Deprecated. since RTSJ 2.0, repleace by getMaxInitialMemoryArea.

Gets the limit on the amount of memory the schedulable may allocate in its initial memory area. Units are in bytes.

Returns:

the allocation limit in the schedulable's initial memory area. When zero, no allocation is allowed in the initial memory area. When the returned value is NO_MAX then there is no limit for allocation in the initial memory area.

setAllocationRate

@Deprecated
public void setAllocationRate(long allocationRate)

Deprecated. RTSJ 2.0

Sets the limit on the rate of allocation in the heap.

Changes to this parameter take place at the next object allocation for each associated schedulable, on an individual basis. Schedulables which are in current violation of the newly configured value will simply receive an StaticOutOfMemoryError on violating allocations. Because this MemoryParameters may be associated with more than one schedulable, on a multiprocessor system there may be some implementation-defined delay before executing schedulables detect the parameter changes.

Parameters:

allocationRate - Units are in bytes per second of wall-clock time. When allocationRate is zero, no allocation is allowed in the heap. To specify no limit, use NO_MAX. Measurement starts when the schedulable starts; not when it is constructed. Enforcement of the allocation rate is an implementation option. When the implementation does not enforce allocation rate limits, it treats all non-zero allocation rate limits as NO_MAX.

Throws:

StaticIllegalArgumentException - when any value other than positive, zero, or NO_MAX is passed as the value of allocationRate.

setAllocationRateIfFeasible

@Deprecated
public boolean setAllocationRateIfFeasible(long allocationRate)

Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate.

Sets the limit on the rate of allocation in the heap. When this MemoryParameters object is currently associated with one or more schedulables 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.

Changes to this parameter take place at the next object allocation for each associated schedulable, on an individual basis. Schedulables which are in current violation of the newly configured value will simply receive an StaticOutOfMemoryError on violating allocations. Because this MemoryParameters may be associated with more than one schedulable, on a multiprocessor system there may be some implementation-defined delay before executing schedulables detect the parameter changes.

Parameters:

allocationRate - Units in bytes per second of wall-clock time. When 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. When the implementation does not enforce allocation rate limits, it treats all non-zero allocation rate limits as NO_MAX.

Returns:

true when the request was fulfilled.

Throws:

StaticIllegalArgumentException - when any value other than positive, zero, or NO_MAX is passed as the value of allocationRate.

setMaxImmortalIfFeasible

@Deprecated
public boolean setMaxImmortalIfFeasible(long maximum)

Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate

Sets the limit on the amount of memory the schedulable may allocate in the immortal area.

Changes to this parameter take place at the next object allocation for each associated schedulable, on an individual basis. Schedulables which are in current violation of the newly configured value will simply receive an StaticOutOfMemoryError on violating allocations. Because this MemoryParameters may be associated with more than one schedulable, on a multiprocessor system there may be some implementation-defined delay before executing schedulables detect the parameter changes.

Parameters:

maximum - Units in bytes. When zero, no allocation allowed in immortal. To specify no limit, use NO_MAX.

Returns:

true when the value is set, false when any of the schedulables have already allocated more than the given value. In this case the call has no effect.

Throws:

StaticIllegalArgumentException - when any value other than positive, zero, or NO_MAX is passed as the value of maximum.

setMaxMemoryAreaIfFeasible

@Deprecated
public boolean setMaxMemoryAreaIfFeasible(long maximum)

Deprecated. as of RTSJ 2.0, since the framework for feasibility analysis is inadequate.

Sets the limit on the amount of memory the schedulable may allocate in its initial memory area.

Changes to this parameter take place at the next object allocation for each associated schedulable, on an individual basis. Schedulables which are in current violation of the newly configured value will simply receive an StaticOutOfMemoryError on violating allocations. Because this MemoryParameters may be associated with more than one schedulable, on a multiprocessor system there may be some implementation-defined delay before executing schedulables detect the parameter changes.

Parameters:

maximum - Units in bytes. When zero, no allocation allowed in the initial memory area. To specify no limit, use UNLIMITED.

Returns:

true when the value is set, false when any of the schedulables have already allocated more than the given value. In this case the call has no effect.

Throws:

StaticIllegalArgumentException - when any value other than positive, zero, or NO_MAX is passed as the value of maximum.