javax.realtime
Class MemoryArea

java.lang.Object
  javax.realtime.MemoryArea

Direct Known Subclasses:

HeapMemory, ImmortalMemory, ImmortalPhysicalMemory, 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.

MemoryArea

protected MemoryArea(long size)

Create an instance of MemoryArea.

Parameters:

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

Throws:

java.lang.IllegalArgumentException - Thrown if size is less than zero.

java.lang.OutOfMemoryError - Thrown if there is insufficient memory for the MemoryArea object or for the backing memory.

MemoryArea

protected MemoryArea(SizeEstimator size)

Create an instance of MemoryArea.

Parameters:

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

Throws:

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

java.lang.OutOfMemoryError - Thrown if there is insufficient memory for the MemoryArea object or for the backing memory.

MemoryArea

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

Create an instance of MemoryArea.

Parameters:

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

logic - The run() method of this object will be called whenever enter() is called. If logic is null, this constructor is equivalent to MemoryArea(long size).

Throws:

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

java.lang.OutOfMemoryError - Thrown if there is insufficient memory for the MemoryArea object or for the backing memory.

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

MemoryArea

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

Create an instance of MemoryArea.

Parameters:

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

logic - The run() method of this object will be called whenever enter() is called. If logic is null, this constructor is equivalent to MemoryArea(SizeEstimator size).

Throws:

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

java.lang.OutOfMemoryError - Thrown if there is insufficient memory for the MemoryArea object or for the backing memory.

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

enter

public void enter()

Associate this memory area with the current schedulable object 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:

java.lang.IllegalThreadStateException - Thrown if the caller is a Java thread.

java.lang.IllegalArgumentException - Thrown if the caller is a schedulable object and no non-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 is allocated in the current allocation context and contains information about the exception it replaces.

MemoryAccessError - Thrown if caller is a no-heap schedulable object and this memory area's logic value is allocated in heap memory.

enter

public void enter(java.lang.Runnable logic)

Associate this memory area with the current schedulable object 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:

java.lang.IllegalThreadStateException - Thrown if the caller is a Java thread.

java.lang.IllegalArgumentException - Thrown if the caller is a schedulable object 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 is allocated in the current allocation context and contains information about the exception it replaces.

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:

java.lang.IllegalArgumentException - Thrown if 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 to 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)

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

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

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

newInstance

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

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

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.

java.lang.IllegalArgumentException - Thrown if type is null.

java.lang.InstantiationException - Thrown if the specified class object could not be instantiated. Possible causes are: it is an interface, it is abstract, it is an array, or an exception was thrown by the constructor.

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

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

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

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

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

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 - Thrown if an unexpected exception has occurred in a static initializer

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

java.lang.IllegalArgumentException - Thrown if 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 - Thrown if 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 - Thrown if the underlying constructor throws an exception.

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

size

public long size()

Query 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)

Execute 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 - Thrown if logic is null.