javax.realtime
Class ScopedMemory

java.lang.Object
  javax.realtime.MemoryArea
      javax.realtime.ScopedMemory

Direct Known Subclasses:

LTMemory, LTPhysicalMemory, StackedMemory, VTMemory, VTPhysicalMemory

public abstract class ScopedMemory
extends MemoryArea

Jamaica Real-Time Specification for Java class ScopedMemory

A memory area of this type enables region-based memory allocation, i.e., objects allocated in ScopedMemory have a lifetime that ends abruptly when the last schedulable object leaves this memory area.

The memory allocated in scoped memory is not subject to garbage collection. It is hence safe to access this memory from within a NoHeapRealtimeThread or an AbstractAsyncEventHandler with no-heap set to true.

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

Field Summary

Fields inherited from class javax.realtime.MemoryArea

memoryAreaHeapLock

Constructor Summary

	ScopedMemory(long size) Constructor to create an instance of ScopedMemory with the given initial size.
protected	ScopedMemory(long backingMemorySize, long containerSize, Runnable logic) Constructor for a memory area with given backing memory & container sizes for stacked memory, also sets a logic.
	ScopedMemory(long size, Runnable logic) Constructor to create an instance of ScopedMemory with the given initial size and default logic.
	ScopedMemory(SizeEstimator size) Constructor to create an instance of ScopedMemory with the given initial size.
	ScopedMemory(SizeEstimator size, Runnable logic) Constructor to create an instance of ScopedMemory with the given initial size and default 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(Runnable logic) enter this memory area and execute the given logic.
void	executeInArea(Runnable logic) executeInArea executes a code sequence given as logic in this memory area.
long	getMaximumSize() getMaximumSize returns the maximum size this memory area may grow to.
ScopedMemory	getParent() Return the parent memory area, when there is a parent and it is a scoped memory.
Object	getPortal() getPortal returns a reference to the portal object of this ScopedMemory.
int	getReferenceCount() getReferenceCount returns the reference count of this memory area.
void	join() join waits for the reference count of this memory area to drop to zero.
void	join(HighResolutionTime time) join waits for the reference count of this memory area to drop to zero.
void	joinAndEnter() joinAndEnter combines join() and enter() such that no other schedulable object may enter() in between the join() and the enter().
void	joinAndEnter(HighResolutionTime time) joinAndEnter combines join() and enter() such that no other schedulable object may enter() in between the join() and the enter().
void	joinAndEnter(Runnable logic) joinAndEnter combines join() and enter() such that no other schedulable object may enter() in between the join() and the enter().
void	joinAndEnter(Runnable logic, HighResolutionTime time) joinAndEnter combines join() and enter() such that no other schedulable object may enter() in between the join() and the enter().
void	setPortal(Object object) setPortal sets the portal object of this memory area to the argument.
String	toString() toString creates a string representation of this memory area of the form "Scoped memory # "+ num with num being a unique identifier for this memory area.

Methods inherited from class javax.realtime.MemoryArea

clearMemory, createStackedMemory, freeStacked, getMemoryArea, memoryConsumed, memoryNeedsToBeCleared, memoryNeedsToBeFreed, memoryRemaining, newArray, newInstance, newInstance, size

Methods inherited from class java.lang.Object

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

Constructor Detail

ScopedMemory

public ScopedMemory(long size)

Constructor to create an instance of ScopedMemory with the given initial size.

Parameters:

size - The size of the memory area in bytes.

Throws:

IllegalArgumentException - if size < 0

OutOfMemoryError - if there is insufficient free memory on the heap.

ScopedMemory

public ScopedMemory(long size,
                    Runnable logic)

Constructor to create an instance of ScopedMemory with the given initial size and default logic.

Parameters:

size - The size of the memory area in bytes.

logic - The default logic to be executed on a call to enter().

Throws:

IllegalArgumentException - if size < 0

OutOfMemoryError - if there is insufficient free memory on the heap.

ScopedMemory

protected ScopedMemory(long backingMemorySize,
                       long containerSize,
                       Runnable logic)

Constructor for a memory area with given backing memory & container sizes for stacked memory, also sets a logic.

Parameters:

backingMemorySize - size of the stacked memory scope.

containerSize - size of the stacked memory backing memory, set to 0 for stacked memory guests.

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

Throws:

IllegalArgumentException - if backingMemorySize < 0 or containerSize < 0

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

See Also:

StackedMemory

ScopedMemory

public ScopedMemory(SizeEstimator size)

Constructor to create an instance of ScopedMemory with the given initial size.

Parameters:

size - an instance of SizeEstimator that determines the size of the memory area.

Throws:

IllegalArgumentException - if size == null

OutOfMemoryError - if there is insufficient free memory on the heap.

ScopedMemory

public ScopedMemory(SizeEstimator size,
                    Runnable logic)

Constructor to create an instance of ScopedMemory with the given initial size and default logic.

Parameters:

size - an instance of SizeEstimator that determines the size of the memory area.

logic - The default logic to be executed on a call to enter().

Throws:

IllegalArgumentException - if size == null

OutOfMemoryError - if there is insufficient free memory on the heap.

Method Detail

enter

public void enter()
           throws ScopedCycleException

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

Overrides:

enter in class MemoryArea

Throws:

ScopedCycleException - if entering this scope has a parent and we enter it from a different parent (i.e., the single parent rule is broken).

ThrowBoundaryError - thrown if an exception is thrown by the logic executed and the exception cannot be propagated out of this scope since that would cause an IllegalAssignmentError. In this case, the exception is replaced by a ThrowBoundaryError.

IllegalArgumentException - iff no logic was provided to the constructor or the logic that was provided was null.

enter

public void enter(Runnable logic)
           throws ScopedCycleException

enter this memory area and execute the given logic.

Overrides:

enter in class MemoryArea

Parameters:

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

Throws:

ScopedCycleException - if entering this scope has a parent and we enter it from a different parent (i.e., the single parent rule is broken).

ThrowBoundaryError - thrown if an exception is thrown by the logic executed and the exception cannot be propagated out of this scope since that would cause an IllegalAssignmentError. In this case, the exception is replaced by a ThrowBoundaryError.

IllegalArgumentException - if logic is null.

getMaximumSize

public long getMaximumSize()

getMaximumSize returns the maximum size this memory area may grow to.

JamaicaVM currently does not support growing memory areas, i.e., the maximum size is always equal to the size.

Returns:

the maximum size this memory area may grow to.

getPortal

public Object getPortal()
                 throws MemoryAccessError,
                        IllegalAssignmentError

getPortal returns a reference to the portal object of this ScopedMemory.

Returns:

the portal object or null if none was set.

Throws:

IllegalAssignmentError - if portal cannot be assigned to the current memory area.

MemoryAccessError

setPortal

public void setPortal(Object object)

setPortal sets the portal object of this memory area to the argument.

Parameters:

object - the new portal.

Throws:

IllegalAssignmentError - if object cannot be assigned to an object stored in this memory area.

InaccessibleAreaException - if this is not on the scope stack.

getReferenceCount

public int getReferenceCount()

getReferenceCount returns the reference count of this memory area. The reference count is increased whenever this memory area is entered, it is decreased when it is exited.

Returns:

the current reference count.

getParent

public ScopedMemory getParent()

Return the parent memory area, when there is a parent and it is a scoped memory. This means that if the parent scope is immortal or heap, null is returned. This reduces the need for casting the returned value. This method is new in RTSJ 1.1; but in 1.1, the return type will be ScopedAllocationContext, an interface that has not yet been added.

Returns:

null or the parent scope

Since:

RTSJ 1.1

toString

public String toString()

toString creates a string representation of this memory area of the form "Scoped memory # "+ num with num being a unique identifier for this memory area.

Overrides:

toString in class Object

Returns:

a string representation of this.

join

public void join(HighResolutionTime time)
          throws InterruptedException

join waits for the reference count of this memory area to drop to zero. Do not wait if the reference count is already zero.

Parameters:

time - An absolute or relative deadline for the wait.

Throws:

InterruptedException - if wait is interrupted by Thread.interrupt() or AsynchronouslyInterruptedException.fire().

IllegalArgumentException - if time is null.

join

public void join()
          throws InterruptedException

join waits for the reference count of this memory area to drop to zero. Do not wait if the reference count is already zero.

Throws:

InterruptedException - if wait is interrupted by Thread.interrupt() or AsynchronouslyInterruptedException.fire().

joinAndEnter

public void joinAndEnter()
                  throws InterruptedException

joinAndEnter combines join() and enter() such that no other schedulable object may enter() in between the join() and the enter().

Throws:

InterruptedException - if wait is interrupted by Thread.interrupt() or AsynchronouslyInterruptedException.fire().

ScopedCycleException - if entering this scope has a parent and we enter it from a different parent (i.e., the single parent rule is broken).

ThrowBoundaryError - thrown if an exception is thrown by the logic executed and the exception cannot be propagated out of this scope since that would cause an IllegalAssignmentError. In this case, the exception is replaced by a ThrowBoundaryError.

IllegalArgumentException - if logic is null.

joinAndEnter

public void joinAndEnter(HighResolutionTime time)
                  throws InterruptedException

joinAndEnter combines join() and enter() such that no other schedulable object may enter() in between the join() and the enter().

Parameters:

time - An absolute or relative deadline for the wait.

Throws:

InterruptedException - if wait is interrupted by Thread.interrupt() or AsynchronouslyInterruptedException.fire().

ScopedCycleException - if entering this scope has a parent and we enter it from a different parent (i.e., the single parent rule is broken).

ThrowBoundaryError - thrown if an exception is thrown by the logic executed and the exception cannot be propagated out of this scope since that would cause an IllegalAssignmentError. In this case, the exception is replaced by a ThrowBoundaryError.

IllegalArgumentException - if time is null.

joinAndEnter

public void joinAndEnter(Runnable logic)
                  throws InterruptedException

joinAndEnter combines join() and enter() such that no other schedulable object may enter() in between the join() and the enter().

Parameters:

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

Throws:

InterruptedException - if wait is interrupted by Thread.interrupt() or AsynchronouslyInterruptedException.fire().

ScopedCycleException - if entering this scope has a parent and we enter it from a different parent (i.e., the single parent rule is broken).

ThrowBoundaryError - thrown if an exception is thrown by the logic executed and the exception cannot be propagated out of this scope since that would cause an IllegalAssignmentError. In this case, the exception is replaced by a ThrowBoundaryError.

IllegalArgumentException - if logic is null.

joinAndEnter

public void joinAndEnter(Runnable logic,
                         HighResolutionTime time)
                  throws InterruptedException

joinAndEnter combines join() and enter() such that no other schedulable object may enter() in between the join() and the enter().

Parameters:

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

time - An absolute or relative deadline for the wait.

Throws:

InterruptedException - if wait is interrupted by Thread.interrupt() or AsynchronouslyInterruptedException.fire().

ScopedCycleException - if entering this scope has a parent and we enter it from a different parent (i.e., the single parent rule is broken).

ThrowBoundaryError - thrown if an exception is thrown by the logic executed and the exception cannot be propagated out of this scope since that would cause an IllegalAssignmentError. In this case, the exception is replaced by a ThrowBoundaryError.

IllegalArgumentException - if logic is null or time is null.

executeInArea

public void executeInArea(Runnable logic)
                   throws InaccessibleAreaException

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

Overrides:

executeInArea in class MemoryArea

Parameters:

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

Throws:

InaccessibleAreaException