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

Jamaica Realtime Specification for Java class MemoryArea.

MemoryArea provides the abstract base class for all allocation environments.

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

Constructor Summary

protected	MemoryArea(long sizeInBytes) Constructor for a memory area of given size.
protected	MemoryArea(long sizeInBytes, java.lang.Runnable logic) Constructor for a memory area that of given size in bytes and sets a logic.
protected	MemoryArea(SizeEstimator size) Constructor for a memory area that gets its size from a SizeEstimator.
protected	MemoryArea(SizeEstimator size, java.lang.Runnable logic) Constructor for a memory area that of given size from a SizeEstimator and sets a logic.

Method Summary

void	enter() enter enters this memory area and executes the logic that was passed to this memory area's constructor.
void	enter(java.lang.Runnable logic) enter enters this memory area and executes the given logic.
void	executeInArea(java.lang.Runnable logic) executeInArea executes a code sequence given as logic in this memory area.
protected void	finalize() Finalize method to free the memory of this MemoryArea.
static MemoryArea	getMemoryArea(java.lang.Object object) getMemoryArea returns the memory area a given object was allocated in.
long	memoryConsumed() memoryConsumed returns the number of bytes of memory of this memory area that have been consumed.
long	memoryRemaining() memoryRemaining returns the number of available bytes left in this memory area.
java.lang.Object	newArray(java.lang.Class type, int number) Allocate a new array with number elements in this memory area.
java.lang.Object	newInstance(java.lang.Class type) allocate a new instance of class type in this memory area.
java.lang.Object	newInstance(java.lang.reflect.Constructor c, java.lang.Object[] args) newInstance allocates a new instance using the given constructor and passign arguments to this constructor.
long	size() size returns the size of this memory area in bytes.

Methods inherited from class java.lang.Object

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

Constructor Detail

MemoryArea

protected MemoryArea(long sizeInBytes)

Constructor for a memory area of given size.

Parameters:

sizeInBytes - size of the area in bytes.

Throws:

java.lang.IllegalArgumentException - if sizeInBytes < 0 or this is called by a user-defined subclass that does not know about the memory area implementation details.

java.lang.OutOfMemoryError - if there is not sufficient memory available for the new MemoryArea.

MemoryArea

protected MemoryArea(SizeEstimator size)

Constructor for a memory area that gets its size from a SizeEstimator.

Parameters:

size - the requested size.

Throws:

java.lang.IllegalArgumentException - if size is null or this is called by a user-defined subclass that does not know about the memory area implementation details.

java.lang.OutOfMemoryError - if there is not sufficient memory available for the new MemoryArea.

MemoryArea

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

Constructor for a memory area that of given size in bytes and sets a logic.

Parameters:

sizeInBytes - size of the area in bytes.

logic - the logic to be associated with this memory area. May be null not to set a default logic.

Throws:

java.lang.IllegalArgumentException - if sizeInBytes < 0 or this is called by a user-defined subclass that does not know about the memory area implementation details.

java.lang.OutOfMemoryError - if there is not sufficient memory available for the new MemoryArea.

MemoryArea

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

Constructor for a memory area that of given size from a SizeEstimator and sets a logic.

Parameters:

size - size of the area.

logic - the logic to be associated with this memory area.

Throws:

java.lang.IllegalArgumentException - if size is null or this is called by a user-defined subclass that does not know about the memory area implementation details.

java.lang.OutOfMemoryError - if there is not sufficient memory available for the new MemoryArea.

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Finalize method to free the memory of this MemoryArea. Since there is no specified way to release the memory of a memory area explicitly, this is done by this finalize method. However, since the execution time of the finalizer is not guaranteed by the system, and the memory may remain unreclaimed for too long, this method should be called explicitly by client code to make sure that the memory is reclaimed immediately when it is not needed any longer.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.IllegalArgumentException - iff this is currently in use (i.e., it is either heap or immortal or it is scoped memory that as a non-zero enter count.

java.lang.Throwable - this method may throw any exception, it will be ignored by the finalizer thread or by Runtime.runFinalization.

enter

public void enter()

enter enters this memory area and executes the logic that was passed to this memory area's constructor.

Throws:

java.lang.IllegalArgumentException - if no logic was provided to the constructor or the logic that was provided was null.

java.lang.IllegalStateException - iff the caller is a Java thread and -strictRTSJ is set.

enter

public void enter(java.lang.Runnable logic)

enter enters this memory area and executes the given logic.

Parameters:

logic - the code to be executed in this memory area.

Throws:

java.lang.IllegalArgumentException - if logic is null.

java.lang.IllegalStateException - iff the caller is a Java thread and -strictRTSJ is set.

getMemoryArea

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

getMemoryArea returns the memory area a given object was allocated in.

Parameters:

object - the object, must not be null.

Returns:

the memory ara object was allocated in. HeapMemory.instance() for all objects that were allocated on the normal heap.

memoryConsumed

public long memoryConsumed()

memoryConsumed returns the number of bytes of memory of this memory area that have been consumed. For memory areas that are freed explicitly by the user (e.g., by exiting a scoped memory area), the result is exact. For other memory areas (that may be under the control of the garbage collector), the result may be an estimation. 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:

number of bytes consumed from this memory area.

memoryRemaining

public long memoryRemaining()

memoryRemaining returns the number of available bytes left in this memory area. This may be an estimation of the amount of available memory. In JamaicaVM, memoryRemainging for HeapMemory is the total heap memory minus memoryConsumed().

Returns:

the number of free bytes in this memory area.

newArray

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

Allocate a new array with number elements in this memory area. This method is save to be used concurrently by several threads, it synchronizes on this.

Parameters:

type - the array type

number - the number of elements of the array.

Returns:

the new array object allocated from this memory area.

Throws:

java.lang.IllegalArgumentException - iff number is negative, type is null or type is Void.TYPE.

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

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

newInstance

public java.lang.Object newInstance(java.lang.Class type)
                             throws java.lang.IllegalAccessException,
                                    java.lang.IllegalArgumentException,
                                    java.lang.InstantiationException,
                                    java.lang.OutOfMemoryError,
                                    java.lang.ExceptionInInitializerError,
                                    InaccessibleAreaException

allocate a new instance of class type in this memory area. Call the constructor with empty arugment list. This method is save to be used concurrently by several threads, it synchronizes on this.

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.IllegalArgumentException,
                                    java.lang.InstantiationException,
                                    java.lang.OutOfMemoryError,
                                    java.lang.ExceptionInInitializerError,
                                    InaccessibleAreaException

newInstance allocates a new instance using the given constructor and passign 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.

size

public long size()

size returns the size of this memory area in bytes.

Returns:

the size in bytes.

executeInArea

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

executeInArea executes a code sequence given as logic in this memory area.

Parameters:

logic - the logic whose run method is to be executed in this memory area.

Throws:

InaccessibleAreaException