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.

In JamaicaVM, application code is not permitted to create instances of user- defined direct subclasses of MemoryArea.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MemoryArea(long sizeInBytes) Equivalent to MemoryArea(long, Runnable) with the argument list (size, null).
protected	MemoryArea(long sizeInBytes, 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.
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.
void	executeInArea(java.lang.Runnable logic) Executes the run() method from the logic parameter using this memory area as the current allocation context.
static MemoryArea	getMemoryArea(java.lang.Object object) Gets the MemoryArea in which the given object is located.
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.
java.lang.Object	newInstance(java.lang.Class<?> type) Allocates an object in this memory area.
java.lang.Object	newInstance(java.lang.reflect.Constructor<?> c, java.lang.Object[] args) Allocates a new instance using the given constructor and passing arguments to this constructor.
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 sizeInBytes)

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

Parameters:

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

Throws:

java.lang.IllegalArgumentException - when size is less than zero.

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

java.lang.UnsupportedOperationException - in JamaicaVM when a user-defined subclass does not know about the memory area implementation details.

MemoryArea

protected MemoryArea(SizeEstimator size)

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:

java.lang.IllegalArgumentException - when the size parameter is null, or size.getEstimate() is negative.

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

java.lang.UnsupportedOperationException - in JamaicaVM when a user-defined subclass does not know about the memory area implementation details.

MemoryArea

protected MemoryArea(long sizeInBytes,
                     java.lang.Runnable logic)

Creates an instance of MemoryArea.

Parameters:

sizeInBytes - 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:

java.lang.IllegalArgumentException - when the size parameter is less than zero.

java.lang.OutOfMemoryError - 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.

java.lang.UnsupportedOperationException - in JamaicaVM when a user-defined subclass does not know about the memory area implementation details.

MemoryArea

protected MemoryArea(SizeEstimator size,
                     java.lang.Runnable logic)

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:

java.lang.IllegalArgumentException - when size is null or size.getEstimate() is negative.

java.lang.OutOfMemoryError - when there is insufficient memory for the MemoryArea object or for its allocation are in its backing store.

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

java.lang.UnsupportedOperationException - in JamaicaVM when a user-defined subclass does not know about the memory area implementation details.

Method Detail

enter

public 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. 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:

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

java.lang.IllegalArgumentException - 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.

java.lang.IllegalStateException - JamaicaVM: when the caller is a non-realtime Java thread and -strictRTSJ is set.

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:

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

java.lang.IllegalArgumentException - 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.

java.lang.IllegalStateException - JamaicaVM: when the caller is a non-realtime Java thread and -strictRTSJ is set.

getMemoryArea

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

Gets the MemoryArea in which the given object is located.

Parameters:

object - the object, must not be null.

Returns:

the instance of MemoryArea from which object was allocated.

Throws:

java.lang.IllegalArgumentException - 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.

In JamaicaVM, the memoryConsumed() for HeapMemory is amount of allocated (i.e., non-free) memory. It is an upper bound for the amount of reachable memory.

Returns:

the amount of remaining memory in bytes.

memoryRemaining

public long memoryRemaining()

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

In JamaicaVM, memoryRemaining for HeapMemory is the total heap memory minus memoryConsumed().

Returns:

the amount of remaining memory in bytes.

newArray

public java.lang.Object newArray(java.lang.Class<?> type,
                                 int number)
                          throws java.lang.IllegalArgumentException,
                                 java.lang.OutOfMemoryError

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

In JamaicaVM this method is save to be used concurrently by several threads, it synchronizes on this.

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:

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

java.lang.OutOfMemoryError - when space in the memory area is exhausted.

java.lang.SecurityException - when the caller does not have permission to create a new instance.

newInstance

public java.lang.Object newInstance(java.lang.Class<?> type)
                             throws java.lang.IllegalAccessException,
                                    java.lang.InstantiationException

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

Parameters:

type - the type of the new object that is to be allocated.

Returns:

the new instance allocated from this memory area.

Throws:

java.lang.IllegalAccessException - thrown if class or constructor is inaccessible.

java.lang.IllegalArgumentException - iff type is null.

java.lang.InstantiationException - if object could not be instantiated (due to type being abstract or an interface or the constructor caused an exception)

java.lang.OutOfMemoryError - iff the space in this memory area is exhausted

java.lang.ExceptionInInitializerError - iff initialization of class type caused an exception.

InaccessibleAreaException - iff this memory area is not accessible, i.e. not on the memory area stack.

newInstance

public java.lang.Object newInstance(java.lang.reflect.Constructor<?> c,
                                    java.lang.Object[] args)
                             throws java.lang.IllegalAccessException,
                                    java.lang.InstantiationException,
                                    java.lang.reflect.InvocationTargetException

Allocates a new instance using the given constructor and passing arguments to this constructor.

Parameters:

c - the constructor of the new instance

args - the arguments to be passed to the constructor

Returns:

the new instance allocated from this memory area.

Throws:

java.lang.IllegalAccessException - thrown if type is inaccessible

java.lang.IllegalArgumentException - iff c is null or args does not contain the number of arguments required by c (args may be null if the arguments list is empty).

java.lang.InstantiationException - if object could not be instantiated (due to type being abstract or an interface or the constructor caused an exception)

java.lang.OutOfMemoryError - iff the space in this memory area is exhausted

java.lang.ExceptionInInitializerError - iff initialization of class type caused an exception.

InaccessibleAreaException - iff this memory area is not accessible, i.e. not on the memory area stack.

java.lang.reflect.InvocationTargetException

size

public long size()

Queries the size of the memory area. The returned value is the current size. The 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)

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:

java.lang.IllegalArgumentException - when logic is null.