javax.realtime

Class ScopedMemory

java.lang.Object

javax.realtime.MemoryArea

javax.realtime.ScopedMemory

Direct Known Subclasses:

LTMemory, LTPhysicalMemory, VTMemory, VTPhysicalMemory

public class ScopedMemory
extends MemoryArea

Equivalent to and superseded by ScopedMemory.

Constructor Summary

Constructors

Constructor and Description
ScopedMemory(long sizeInBytes) Equivalent to ScopedMemory(long, Runnable) with the argument list (size, null).
ScopedMemory(long sizeInBytes, Runnable logic) Creates a new ScopedMemory area with the given parameters.
ScopedMemory(SizeEstimator size) Equivalent to ScopedMemory(long, Runnable) with the argument list (size.getEstimate(), null).
ScopedMemory(SizeEstimator size, Runnable logic) Equivalent to ScopedMemory(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(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(Runnable logic) Executes the run method from the logic parameter using this memory area as the current allocation context.
long	getMaximumSize() Gets the maximum size this memory area can attain.
Object	getPortal() Obtains a reference to the portal object in this instance of ScopedMemory.
int	getReferenceCount() Returns the reference count of this ScopedMemory.
void	join() Waits until the reference count of this ScopedMemory goes down to zero.
void	join(HighResolutionTime<?> time) Waits at most until the time designated by the time parameter for the reference count of this ScopedMemory to drop to zero.
void	joinAndEnter() In the error-free case, joinAndEnter() combines join();enter(); such that no enter() from another schedulable can intervene between the two method invocations.
void	joinAndEnter(HighResolutionTime<?> time) In the error-free case, joinAndEnter() combines join();enter(); such that no enter() from another schedulable can intervene between the two method invocations.
void	joinAndEnter(Runnable logic) In the error-free case, joinAndEnter() combines join();enter(); such that no enter() from another schedulable can intervene between the two method invocations.
void	joinAndEnter(Runnable logic, HighResolutionTime<?> time) In the error-free case, joinAndEnter() combines join();enter(); such that no enter() from another schedulable can intervene between the two method invocations.
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.
Object	newArray(Class<?> type, int number) Allocates an array of the given type in this memory area.
<T> T	newInstance(Class<T> type) Allocates an object in this memory area.
<T> T	newInstance(Constructor<T> c, Object[] args) Allocates an object in this memory area.
void	setPortal(Object portal) Sets the portal object of the memory area represented by this instance of ScopedMemory to the given object.
long	size() Queries the size of the memory area.
String	toString() Returns a user-friendly representation of this ScopedMemory of the form ScopedMemory#<num> where <num> is a number that uniquely identifies this scoped memory area.

Methods inherited from class javax.realtime.MemoryArea

enter, enter, enter, enter, enter, executeInArea, executeInArea, executeInArea, executeInArea, executeInArea, getMemoryArea, mayHoldReferenceTo, mayHoldReferenceTo, newArrayInArea

Methods inherited from class java.lang.Object

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

Constructor Detail

ScopedMemory

public ScopedMemory(long sizeInBytes)

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

Throws:

StaticIllegalArgumentException - when size is less than zero.

OutOfMemoryError - when there is insufficient memory for the ScopedMemory object or for the backing memory.

Parameters:

sizeInBytes - of the new ScopedMemory area in bytes.

ScopedMemory

public ScopedMemory(SizeEstimator size)

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

Throws:

StaticIllegalArgumentException - when size is null, or size.getEstimate() is negative.

OutOfMemoryError - when there is insufficient memory for the ScopedMemory object or for the backing memory.

Parameters:

size - The size of the new ScopedMemory area estimated by an instance of SizeEstimator.

ScopedMemory

public ScopedMemory(SizeEstimator size,
                    Runnable logic)

Equivalent to ScopedMemory(long, Runnable) with the argument list (size.getEstimate(), logic).

Throws:

StaticIllegalArgumentException - when size is null, or size.getEstimate() is negative.

OutOfMemoryError - when there is insufficient memory for the ScopedMemory object or for the backing memory.

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

Parameters:

size - The size of the new ScopedMemory area estimated by an instance of SizeEstimator.

logic - The logic which will use the memory represented by this as its initial memory area. When logic is null, this constructor is equivalent to constructing the memory area without a logic value.

ScopedMemory

public ScopedMemory(long sizeInBytes,
                    Runnable logic)

Creates a new ScopedMemory area with the given parameters.

Throws:

StaticIllegalArgumentException - when size is less than zero.

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

OutOfMemoryError - when there is insufficient memory for the ScopedMemory object or for the backing memory.

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

Parameters:

sizeInBytes - The size of the new ScopedMemory area in bytes.

logic - The Runnable to execute when this ScopedMemory is entered. When logic is null, this constructor is equivalent to constructing the memory area without a logic value.

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()) or the enter() method exits.

Overrides:

enter in class MemoryArea

Throws:

ScopedCycleException - when this invocation would break the single parent rule.

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

IllegalThreadStateException - when the caller is a Java thread, or when this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the SO that triggered finalization. This would include the scope containing the SO, and the scope (if any) containing the scope containing the SO.

StaticIllegalArgumentException - when the caller is a schedulable and a null value for logic was supplied when the memory area was constructed.

MemoryAccessError - when caller is a schedulable that may not use the heap and this memory area's logic value is allocated in heap memory.

enter

public void enter(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()) or the enter() method exits.

Overrides:

enter in class MemoryArea

Throws:

ScopedCycleException - when this invocation would break the single parent rule.

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

IllegalThreadStateException - when the caller is a Java thread, or when this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the schedulable that triggered finalization. This would include the scope containing the schedulable, and the scope (if any) containing the scope containing the schedulable.

StaticIllegalArgumentException - when the caller is a schedulable and logic is null.

Parameters:

logic - The Runnable object whose run() method should be invoked.

memoryConsumed

public long memoryConsumed()

Description copied from class: MemoryArea

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.

Overrides:

memoryConsumed in class MemoryArea

Returns:

the amount of remaining memory in bytes.

memoryRemaining

public long memoryRemaining()

Description copied from class: MemoryArea

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

Overrides:

memoryRemaining in class MemoryArea

Returns:

the amount of remaining memory in bytes.

size

public long size()

Description copied from class: MemoryArea

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.

Overrides:

size in class MemoryArea

Returns:

the size of the memory area in bytes.

newInstance

public <T> T newInstance(Class<T> type)
                  throws IllegalAccessException,
                         InstantiationException

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

Overrides:

newInstance in class MemoryArea

Throws:

IllegalAccessException - thrown if class or constructor is inaccessible.

StaticIllegalArgumentException - iff type is null.

ExceptionInInitializerError - iff initialization of class type caused an exception.

OutOfMemoryError - iff the space in this memory area is exhausted

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

IllegalThreadStateException - when the caller context in not an instance of Schedulable.

InaccessibleAreaException - when the memory area is not in the schedulable's scope stack.

Type Parameters:

T - The type of the created object

Parameters:

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

Returns:

the new instance allocated from this memory area.

newInstance

public <T> T newInstance(Constructor<T> c,
                         Object[] args)
                  throws IllegalAccessException,
                         InstantiationException,
                         InvocationTargetException

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

Overrides:

newInstance in class MemoryArea

Throws:

IllegalAccessException - thrown if type is inaccessible

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

OutOfMemoryError - iff the space in this memory area is exhausted

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

IllegalThreadStateException - when the caller context in not an instance of Schedulable.

InvocationTargetException

InaccessibleAreaException - when the memory area is not in the schedulable's scope stack.

Type Parameters:

T - The type of the created object

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.

newArray

public Object newArray(Class<?> type,
                       int number)
                throws StaticIllegalArgumentException,
                       OutOfMemoryError,
                       InaccessibleAreaException

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

Overrides:

newArray in class MemoryArea

Throws:

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

OutOfMemoryError - when space in the memory area is exhausted.

IllegalThreadStateException - when the caller context in not an instance of Schedulable.

InaccessibleAreaException - when the memory area is not in the schedulable's scope stack.

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.

executeInArea

public void executeInArea(Runnable logic)
                   throws InaccessibleAreaException

Executes the run method from the logic parameter using this memory area as the current allocation context. This method behaves as if it moves the allocation context down the scope stack to the occurrence of this.

Overrides:

executeInArea in class MemoryArea

Throws:

IllegalThreadStateException - when the caller context in not an instance of Schedulable.

InaccessibleAreaException - when the memory area is not in the schedulable's scope stack.

StaticIllegalArgumentException - when the caller is a schedulable and logic is null.

Parameters:

logic - The runnable object whose run() method should be executed.

getMaximumSize

public long getMaximumSize()

Gets the maximum size this memory area can attain. If this is a fixed size memory area, the returned value will be equal to the initial size.

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

Returns:

the maximum size attainable.

getPortal

public Object getPortal()

Obtains a reference to the portal object in this instance of ScopedMemory.

Assignment rules are enforced on the value returned by getPortal() as if the return value were first stored in an object allocated in the current allocation context, then moved to its final destination.

Throws:

IllegalAssignmentError - when a reference to the portal object cannot be stored in the caller's allocation context; that is, when this is "inner" relative to the current allocation context or not on the caller's scope stack.

IllegalThreadStateException - when the caller context in not an instance of Schedulable.

Returns:

a reference to the portal object or null when there is no portal object. The portal value is always set to null when the contents of the memory are deleted.

setPortal

public void setPortal(Object portal)

Sets the portal object of the memory area represented by this instance of ScopedMemory to the given object. The object must have been allocated in this ScopedMemory instance.

Throws:

IllegalThreadStateException - when the caller context in not an instance of Schedulable.

IllegalAssignmentError - when the caller is a schedulable, and object is not allocated in this scoped memory instance and not null.

InaccessibleAreaException - when the caller is a schedulable, this memory area is not in the caller's scope stack and object is not null.

Parameters:

portal - The object which will become the portal for this. When null the previous portal object remains the portal object for this or when there was no previous portal object then there is still no portal object for this.

getReferenceCount

public int getReferenceCount()

Returns the reference count of this ScopedMemory.

Note that a reference count of 0 reliably means that the scope is not referenced, but other reference counts are subject to artifacts of lazy/eager maintenance by the implementation.

Returns:

the reference count of this ScopedMemory.

join

public void join()
          throws InterruptedException

Waits until the reference count of this ScopedMemory goes down to zero. Returns immediately when the memory is unreferenced.

Throws:

InterruptedException - When this schedulable is interrupted by RealtimeThread.interrupt() or AsynchronouslyInterruptedException.fire() while waiting for the reference count to go to zero.

IllegalThreadStateException - when the caller context in not an instance of Schedulable.

join

public void join(HighResolutionTime<?> time)
          throws InterruptedException

Waits at most until the time designated by the time parameter for the reference count of this ScopedMemory to drop to zero. Returns immediately when the memory area is unreferenced.

Since the time is expressed as a HighResolutionTime, this method is an accurate timer with nanosecond granularity. The actual resolution of the timer and even the quantity it measures depends on the clock associated with time. The delay time may be relative or absolute. When relative, then the delay is the amount of time given by time, and measured by its associated clock. When absolute, then the delay is until the indicated value is reached by the clock. When the given absolute time is less than or equal to the current value of the clock, the call to join() returns immediately.

Throws:

InterruptedException - when this schedulable is interrupted by RealtimeThread.interrupt() or AsynchronouslyInterruptedException.fire() while waiting for the reference count to go to zero.

IllegalThreadStateException - when the caller context in not an instance of Schedulable.

StaticIllegalArgumentException - when the caller is a schedulable and time is null.

UnsupportedOperationException - when the wait operation is not supported using the clock associated with time.

Parameters:

time - When this time is an absolute time, the wait is bounded by that point in time. When the time is a relative time, the wait is bounded by a the specified interval from some time between the time join is called and the time it starts waiting for the reference count to reach zero.

joinAndEnter

public void joinAndEnter()
                  throws InterruptedException

In the error-free case, joinAndEnter() combines join();enter(); such that no enter() from another schedulable can intervene between the two method invocations. The resulting method will wait for the reference count on this ScopedMemory to reach zero, then enter the ScopedMemory and execute the run() method from logic passed in the constructor. When no instance of Runnable was passed to the memory area's constructor, the method throws StaticIllegalArgumentException immediately.

When multiple threads are waiting in joinAndEnter() family methods for a memory area, at most one of them will be released each time the reference count goes to zero.

Note that although joinAndEnter() guarantees that the reference count is zero when the schedulable is released for entry, it does not guarantee that the reference count will remain one for any length of time. A subsequent enter() could raise the reference count to two.

Throws:

InterruptedException - When this schedulable is interrupted by RealtimeThread.interrupt() or AsynchronouslyInterruptedException.fire() while waiting for the reference count to go to zero.

IllegalThreadStateException - when the caller is a Java thread, or when this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the SO that triggered finalization. This would include the scope containing the SO, and the scope (if any) containing the scope containing the SO.

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

ScopedCycleException - when this invocation would break the single parent rule.

StaticIllegalArgumentException - when the caller is a schedulable and no non-null logic value was supplied to the memory area's constructor.

MemoryAccessError - when caller is a non-heap schedulable and this memory area's logic value is allocated in heap memory.

joinAndEnter

public void joinAndEnter(HighResolutionTime<?> time)
                  throws InterruptedException

In the error-free case, joinAndEnter() combines join();enter(); such that no enter() from another schedulable can intervene between the two method invocations. The resulting method will wait for the reference count on this ScopedMemory to reach zero, or for the current time to reach the designated time, then enter the ScopedMemory and execute the run() method from Runnable object passed to the constructor. When no instance of Runnable was passed to the memory area's constructor, the method throws StaticIllegalArgumentException immediately.

When multiple threads are waiting in joinAndEnter family methods for a memory area, at most one of them will be released each time the reference count goes to zero.

Since the time is expressed as a HighResolutionTime, this method has an accurate timer with nanosecond granularity. The actual resolution of the timer and even the quantity it measures depends on the clock associated with time. The delay time may be relative or absolute. When relative, then the calling thread is blocked for at most the amount of time given by time, and measured by its associated clock. When absolute, then the time delay is until the indicated value is reached by the clock. When the given absolute time is less than or equal to the current value of the clock, the call to joinAndEnter behaves effectively like enter().

Note that expiration of time may cause control to enter the memory area before its reference count has gone to zero.

Throws:

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

InterruptedException - When this schedulable is interrupted by RealtimeThread.interrupt() or AsynchronouslyInterruptedException.fire() while waiting for the reference count to go to zero.

IllegalThreadStateException - when the caller context is not an instance of Schedulable, or when this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the instance that triggered finalization. This would include the scope containing the instance, and the scope (if any) containing the scope containing the instance.

ScopedCycleException - when the caller is a schedulable and this invocation would break the single parent rule.

StaticIllegalArgumentException - when the caller is a schedulable, and time is null or null was supplied as logic value to the memory area's constructor.

UnsupportedOperationException - when the wait operation is not supported using the clock associated with time.

MemoryAccessError - when the calling schedulable may not use the heap and this memory area's logic value is allocated in heap memory.

Parameters:

time - The time that bounds the wait.

joinAndEnter

public void joinAndEnter(Runnable logic)
                  throws InterruptedException

In the error-free case, joinAndEnter() combines join();enter(); such that no enter() from another schedulable can intervene between the two method invocations. The resulting method will wait for the reference count on this ScopedMemory to reach zero, then enter the ScopedMemory and execute the run method from logic

When logic is null, throw StaticIllegalArgumentException immediately.

When multiple threads are waiting in joinAndEnter family methods for a memory area, at most one of them will be released each time the reference count goes to zero.

Note that although joinAndEnter() guarantees that the reference count is zero when the schedulable is released for entry, it does not guarantee that the reference count will remain one for any length of time. A subsequent enter() could raise the reference count to two.

Throws:

InterruptedException - When this schedulable is interrupted by RealtimeThread.interrupt() or AsynchronouslyInterruptedException.fire() while waiting for the reference count to go to zero.

IllegalThreadStateException - when the caller is a Java thread, or when this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the SO that triggered finalization. This would include the scope containing the SO, and the scope (if any) containing the scope containing the SO.

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

ScopedCycleException - when this invocation would break the single parent rule.

StaticIllegalArgumentException - when the caller is a schedulable and logic is null.

Parameters:

logic - The Runnable object which contains the code to execute.

joinAndEnter

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

In the error-free case, joinAndEnter() combines join();enter(); such that no enter() from another schedulable can intervene between the two method invocations. The resulting method will wait for the reference count on this ScopedMemory to reach zero, or for the current time to reach the designated time, then enter the ScopedMemory and execute the run method from logic.

Since the time is expressed as a HighResolutionTime, this method is an accurate timer with nanosecond granularity. The actual resolution of the timer and even the quantity it measures depends on the clock associated with time. The delay time may be relative or absolute. When relative, then the delay is the amount of time given by time, and measured by its associated clock. When absolute, then the delay is until the indicated value is reached by the clock. When the given absolute time is less than or equal to the current value of the clock, the call to joinAndEnter behaves effectively like enter(Runnable).

Throws StaticIllegalArgumentException immediately when logic is null.

When multiple threads are waiting in joinAndEnter family methods for a memory area, at most one of them will be released each time the reference count goes to zero.

Note that expiration of time may cause control to enter the memory area before its reference count has gone to zero.

Throws:

InterruptedException - When this schedulable is interrupted by RealtimeThread.interrupt() or AsynchronouslyInterruptedException.fire() while waiting for the reference count to go to zero.

IllegalThreadStateException - when the execution context in not an instance of Schedulable, or when this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the task that triggered finalization. This would include the scope containing the task, and the scope (if any) containing the scope containing the task.

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

ScopedCycleException - when the caller is a schedulable and this invocation would break the single parent rule.

StaticIllegalArgumentException - when the caller is a schedulable and time or logic is null.

UnsupportedOperationException - when the wait operation is not supported using the clock associated with time.

Parameters:

logic - The Runnable object which contains the code to execute.

time - The time that bounds the wait.

toString

public String toString()

Returns a user-friendly representation of this ScopedMemory of the form ScopedMemory#<num> where <num> is a number that uniquely identifies this scoped memory area.

Overrides:

toString in class Object

Returns:

The string representation