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.

Constructor Summary

protected	MemoryArea(long size) Create an instance of MemoryArea.
protected	MemoryArea(long size, java.lang.Runnable logic) Create an instance of MemoryArea.
protected	MemoryArea(SizeEstimator size) Create an instance of MemoryArea.
protected	MemoryArea(SizeEstimator size, java.lang.Runnable logic) Create an instance of MemoryArea.

Method Summary

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.
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.
void	executeInArea(java.lang.Runnable logic) Execute 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 to the total amount of memory currently available for future allocated objects, measured in bytes.
java.lang.Object	newArray(java.lang.Class type, int number) Allocate an array of the given type in this memory area.
java.lang.Object	newInstance(java.lang.Class type) Allocate an object in this memory area.
java.lang.Object	newInstance(java.lang.reflect.Constructor c, java.lang.Object[] args) Allocate an object in this memory area.
long	size() Query 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)

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.

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.

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.

Method Detail

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

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

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

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.