javax.realtime

Class MemoryArea

java.lang.Object

javax.realtime.MemoryArea

Direct Known Subclasses:

PerennialMemory, ScopedMemory, ScopedMemory

public abstract class MemoryArea
extends java.lang.Object

MemoryArea is the abstract base class of all classes dealing with the representations of allocatable memory areas, including the immortal memory area, physical memory and scoped memory areas. This is an abstract class, but no method in this class is abstract. An application should not subclass MemoryArea without complete knowledge of its implementation details.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MemoryArea(long size) Equivalent to MemoryArea(long, Runnable) with the argument list (size, null).
protected	MemoryArea(long size, java.lang.Runnable logic) Creates an instance of MemoryArea.
protected	MemoryArea(SizeEstimator size) Equivalent to MemoryArea(long, Runnable) with the argument list (size.getEstimate(), null).
protected	MemoryArea(SizeEstimator size, java.lang.Runnable logic) Equivalent to MemoryArea(long, Runnable) with the argument list (size.getEstimate(), logic).

Method Summary

Modifier and Type	Method and Description
void	enter() Associates this memory area with the current schedulable for the duration of the execution of the run() method of the instance of Runnable given in the constructor.
boolean	enter(java.util.function.BooleanSupplier logic) Same as enter(Runnable) except that the executed method is called get and a boolean is returned.
double	enter(java.util.function.DoubleSupplier logic) Same as enter(Runnable) except that the executed method is called get and a double is returned.
int	enter(java.util.function.IntSupplier logic) Same as enter(Runnable) except that the executed method is called get and an int is returned.
long	enter(java.util.function.LongSupplier logic) Same as enter(Runnable) except that the executed method is called get and a long is returned.
void	enter(java.lang.Runnable logic) Associates this memory area with the current schedulable for the duration of the execution of the run() method of the given Runnable.
<T> T	enter(java.util.function.Supplier<T> logic) Same as enter(Runnable) except that the executed method is called get and an object is returned.
boolean	executeInArea(java.util.function.BooleanSupplier logic) Same as executeInArea(Runnable) except that the executed method is called get and a boolean is returned.
double	executeInArea(java.util.function.DoubleSupplier logic) Same as executeInArea(Runnable) except that the executed method is called get and a double is returned.
int	executeInArea(java.util.function.IntSupplier logic) Same as executeInArea(Runnable) except that the executed method is called get and an int is returned.
long	executeInArea(java.util.function.LongSupplier logic) Same as executeInArea(Runnable) except that the executed method is called get and a long is returned.
void	executeInArea(java.lang.Runnable logic) Executes the run() method from the logic parameter using this memory area as the current allocation context.
<T> T	executeInArea(java.util.function.Supplier<T> logic) Same as executeInArea(Runnable) except that the executed method is called get and an object is returned.
static MemoryArea	getMemoryArea(java.lang.Object object) Gets the MemoryArea in which the given object is located.
boolean	mayHoldReferenceTo() Determines whether an object A allocated in the memory area represented by this can hold a reference to an object B allocated in the current memory area.
boolean	mayHoldReferenceTo(java.lang.Object value) Determines whether an object A allocated in the memory area represented by this can hold a reference to the object value.
long	memoryConsumed() For memory areas where memory is freed under program control this returns an exact count, in bytes, of the memory currently used by the system for the allocated objects.
long	memoryRemaining() An approximation of the total amount of memory currently available for future allocated objects, measured in bytes.
java.lang.Object	newArray(java.lang.Class<?> type, int number) Allocates an array of the given type in this memory area.
static java.lang.Object	newArrayInArea(java.lang.Object object, java.lang.Class<?> type, int size) A helper method to create an array of type type in the memory area containing object.
<T> T	newInstance(java.lang.Class<T> type) Allocates an object in this memory area.
<T> T	newInstance(java.lang.reflect.Constructor<T> c, java.lang.Object[] args) Allocates an object in this memory area.
long	size() Queries the size of the memory area.

Methods inherited from class java.lang.Object

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

Constructor Detail

MemoryArea

protected MemoryArea(long size,
                     java.lang.Runnable logic)
              throws StaticIllegalArgumentException,
                     StaticOutOfMemoryError,
                     IllegalAssignmentError

Creates an instance of MemoryArea.

Parameters:

size - The size of MemoryArea to allocate, in bytes.

logic - A runnable, whose run() method will be called whenever enter() is called. When logic is null, this constructor is equivalent to MemoryArea(long size).

Throws:

StaticIllegalArgumentException - when the size parameter is less than zero.

StaticOutOfMemoryError - when there is insufficient memory for the MemoryArea object or for its allocation area in its backing store.

IllegalAssignmentError - when storing logic in this would violate the assignment rules.

MemoryArea

protected MemoryArea(SizeEstimator size,
                     java.lang.Runnable logic)
              throws StaticIllegalArgumentException,
                     StaticOutOfMemoryError,
                     IllegalAssignmentError

Equivalent to MemoryArea(long, Runnable) with the argument list (size.getEstimate(), logic).

Parameters:

size - A SizeEstimator object which indicates the amount of memory required by this MemoryArea.

logic - A runnable, whose run() method will be called whenever enter() is called. When logic is null, this constructor is equivalent to MemoryArea(SizeEstimator size).

Throws:

StaticIllegalArgumentException - when size is null or size.getEstimate() is negative.

StaticOutOfMemoryError - when there is insufficient memory for the MemoryArea object or for its allocation area in its backing store.

IllegalAssignmentError - when storing logic in this would violate the assignment rules.

MemoryArea

protected MemoryArea(long size)
              throws StaticIllegalArgumentException,
                     StaticOutOfMemoryError

Equivalent to MemoryArea(long, Runnable) with the argument list (size, null).

Parameters:

size - The size of MemoryArea to allocate, in bytes.

Throws:

StaticIllegalArgumentException - when size is less than zero.

StaticOutOfMemoryError - when there is insufficient memory for the MemoryArea object or for its allocation area in its backing store.

MemoryArea

protected MemoryArea(SizeEstimator size)
              throws StaticIllegalArgumentException,
                     StaticOutOfMemoryError

Equivalent to MemoryArea(long, Runnable) with the argument list (size.getEstimate(), null).

Parameters:

size - A SizeEstimator object which indicates the amount of memory required by this MemoryArea.

Throws:

StaticIllegalArgumentException - when the size parameter is null, or size.getEstimate() is negative.

StaticOutOfMemoryError - when there is insufficient memory for the MemoryArea object or for its allocation area in its backing store.

Method Detail

enter

public void enter()
           throws IllegalTaskStateException,
                  StaticIllegalArgumentException,
                  ThrowBoundaryError,
                  MemoryAccessError

Associates this memory area with the current schedulable for the duration of the execution of the run() method of the instance of Runnable given in the constructor. During this period of execution, this memory area becomes the default allocation context until another default allocation context is selected (using enter, or executeInArea(java.lang.Runnable)) or the enter method exits.

Throws:

IllegalTaskStateException - when the caller context is not an instance of Schedulable.

StaticIllegalArgumentException - when the caller is a schedulable and a null value for logic was supplied when the memory area was constructed.

ThrowBoundaryError - Thrown when the JVM needs to propagate an exception allocated in this scope to (or through) the memory area of the caller. Storing a reference to that exception would cause an IllegalAssignmentError, so the JVM cannot be permitted to deliver the exception. The ThrowBoundaryError instance is preallocated by the VM to avoid cascading creation of ThrowBoundaryError.

MemoryAccessError - when caller is a schedulable that may not use the heap and this memory area's logic value is allocated in heap memory.

enter

public void enter(java.lang.Runnable logic)

Associates this memory area with the current schedulable for the duration of the execution of the run() method of the given Runnable. During this period of execution, this memory area becomes the default allocation context until another default allocation context is selected (using enter, or executeInArea(java.lang.Runnable)) or the enter method exits.

Parameters:

logic - The Runnable object whose run() method should be invoked.

Throws:

IllegalTaskStateException - when the caller context is not an instance of Schedulable.

StaticIllegalArgumentException - when the caller is a schedulable and logic is null.

ThrowBoundaryError - Thrown when the JVM needs to propagate an exception allocated in this scope to (or through) the memory area of the caller. Storing a reference to that exception would cause an IllegalAssignmentError, so the JVM cannot be permitted to deliver the exception. The ThrowBoundaryError instance is preallocated by the VM to avoid cascading creation of ThrowBoundaryError.

enter

public <T> T enter(java.util.function.Supplier<T> logic)

Same as enter(Runnable) except that the executed method is called get and an object is returned. The Supplier.get() method must ensure that the returned object is allocated outside the area, when the area is not a PerennialMemory.

Type Parameters:

T - The type of the object returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

IllegalAssignmentError - when the return value allocated in area and area is not a PerennialMemory.

Since:

RTSJ 2.0

enter

public boolean enter(java.util.function.BooleanSupplier logic)

Same as enter(Runnable) except that the executed method is called get and a boolean is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Since:

RTSJ 2.0

enter

public int enter(java.util.function.IntSupplier logic)

Same as enter(Runnable) except that the executed method is called get and an int is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Since:

RTSJ 2.0

enter

public long enter(java.util.function.LongSupplier logic)

Same as enter(Runnable) except that the executed method is called get and a long is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Since:

RTSJ 2.0

enter

public double enter(java.util.function.DoubleSupplier logic)

Same as enter(Runnable) except that the executed method is called get and a double is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Since:

RTSJ 2.0

getMemoryArea

public static MemoryArea getMemoryArea(java.lang.Object object)

Gets the MemoryArea in which the given object is located.

Returns:

the instance of MemoryArea from which object was allocated.

Throws:

StaticIllegalArgumentException - when the value of object is null.

memoryConsumed

public long memoryConsumed()

For memory areas where memory is freed under program control this returns an exact count, in bytes, of the memory currently used by the system for the allocated objects. For memory areas (such as heap) where the definition of "used" is imprecise, this returns the best value it can generate in constant time.

Returns:

the amount of memory consumed in bytes.

memoryRemaining

public long memoryRemaining()

An approximation of the total amount of memory currently available for future allocated objects, measured in bytes.

Returns:

the amount of remaining memory in bytes.

newArray

public java.lang.Object newArray(java.lang.Class<?> type,
                                 int number)
                          throws StaticIllegalArgumentException,
                                 StaticOutOfMemoryError,
                                 StaticSecurityException

Allocates an array of the given type in this memory area. This method may be concurrently used by multiple threads.

Parameters:

type - The class of the elements of the new array. To create an array of a primitive type use a type such as Integer.TYPE (which would call for an array of the primitive int type.)

number - The number of elements in the new array.

Returns:

a new array of class type, of number elements.

Throws:

StaticIllegalArgumentException - when number is less than zero, type is null, or type is java.lang.Void.TYPE.

StaticOutOfMemoryError - when space in the memory area is exhausted.

StaticSecurityException - when the caller does not have permission to create a new instance.

newArrayInArea

public static java.lang.Object newArrayInArea(java.lang.Object object,
                                              java.lang.Class<?> type,
                                              int size)

A helper method to create an array of type type in the memory area containing object.

Parameters:

object - is the reference for determining the area in which to allocate the array.

type - is the type of the array element for the returned array.

size - is the size of the array to return.

Returns:

a new array of element type with size elements.

Since:

RTSJ 2.0

newInstance

public <T> T newInstance(java.lang.Class<T> type)
                  throws java.lang.IllegalAccessException,
                         StaticIllegalArgumentException,
                         java.lang.InstantiationException,
                         StaticOutOfMemoryError,
                         java.lang.ExceptionInInitializerError,
                         StaticSecurityException

Allocates an object in this memory area. This method may be concurrently used by multiple threads.

Type Parameters:

T - The type of the created object

Parameters:

type - The class of which to create a new instance.

Returns:

a new instance of class type.

Throws:

java.lang.IllegalAccessException - The class or initializer is inaccessible.

StaticIllegalArgumentException - when type is null.

java.lang.InstantiationException - when the specified class object could not be instantiated. Possible causes are it is an interface, it is abstract, or it is an array.

ConstructorCheckedException - a checked exception was thrown by the constructor.

StaticOutOfMemoryError - when space in the memory area is exhausted.

java.lang.ExceptionInInitializerError - when an unexpected exception has occurred in a static initializer.

StaticSecurityException - when the caller does not have permission to create a new instance.

newInstance

public <T> T newInstance(java.lang.reflect.Constructor<T> c,
                         java.lang.Object[] args)
                  throws java.lang.ExceptionInInitializerError,
                         java.lang.IllegalAccessException,
                         StaticIllegalArgumentException,
                         java.lang.InstantiationException,
                         java.lang.reflect.InvocationTargetException,
                         StaticOutOfMemoryError,
                         StaticSecurityException

Allocates an object in this memory area. This method may be concurrently used by multiple threads.

Type Parameters:

T - The type of the created object

Parameters:

c - The constructor for the new instance.

args - An array of arguments to pass to the constructor.

Returns:

a new instance of the object constructed by c.

Throws:

java.lang.ExceptionInInitializerError - when an unexpected exception has occurred in a static initializer

java.lang.IllegalAccessException - when the class or initializer is inaccessible under Java access control.

StaticIllegalArgumentException - when c is null, or the args array does not contain the number of arguments required by c. A null value of args is treated like an array of length 0.

java.lang.InstantiationException - when the specified class object could not be instantiated. Possible causes are it is an interface, it is abstract, it is an array.

java.lang.reflect.InvocationTargetException - when the underlying constructor throws an exception.

StaticOutOfMemoryError - when space in the memory area is exhausted.

StaticSecurityException - when the caller does not have permission to create a new instance.

size

public long size()

Queries the size of the memory area. The returned value is the current size. Current size may be larger than initial size for those areas that are allowed to grow.

Returns:

the size of the memory area in bytes.

executeInArea

public void executeInArea(java.lang.Runnable logic)
                   throws StaticIllegalArgumentException

Executes the run() method from the logic parameter using this memory area as the current allocation context. The effect of executeInArea on the scope stack is specified in the subclasses of MemoryArea.

Parameters:

logic - The runnable object whose run() method should be executed.

Throws:

StaticIllegalArgumentException - when logic is null.

executeInArea

public <T> T executeInArea(java.util.function.Supplier<T> logic)

Same as executeInArea(Runnable) except that the executed method is called get and an object is returned. For a memory are that is not a PerennialMemory, care must be taken that the returned value is assignable to an object allocated in the current area.

Type Parameters:

T - the type of the returned object.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

IllegalAssignmentError - when the return value is not assignable to an object allocated in the current area.

Since:

RTSJ 2.0

executeInArea

public boolean executeInArea(java.util.function.BooleanSupplier logic)

Same as executeInArea(Runnable) except that the executed method is called get and a boolean is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Since:

RTSJ 2.0

executeInArea

public int executeInArea(java.util.function.IntSupplier logic)

Same as executeInArea(Runnable) except that the executed method is called get and an int is returned.

Parameters:

logic - the object whose get method will be executed.

Returns:

a result from the computation.

Since:

RTSJ 2.0

executeInArea

public long executeInArea(java.util.function.LongSupplier logic)

Same as executeInArea(Runnable) except that the executed method is called get and a long is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Since:

RTSJ 2.0

executeInArea

public double executeInArea(java.util.function.DoubleSupplier logic)

Same as executeInArea(Runnable) except that the executed method is called get and a double is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Since:

RTSJ 2.0

mayHoldReferenceTo

public boolean mayHoldReferenceTo()

Determines whether an object A allocated in the memory area represented by this can hold a reference to an object B allocated in the current memory area.

Returns:

true when B can be assigned to a field of A, otherwise false.

Since:

RTSJ 2.0

mayHoldReferenceTo

public boolean mayHoldReferenceTo(java.lang.Object value)

Determines whether an object A allocated in the memory area represented by this can hold a reference to the object value.

Parameters:

value - The object to test.

Returns:

true when value can be assigned to a field of A, otherwise false.

Since:

RTSJ 2.0