javax.realtime

Class ScopedMemory

java.lang.Object

javax.realtime.MemoryArea

javax.realtime.ScopedMemory

Direct Known Subclasses:

LTMemory, LTPhysicalMemory, VTMemory, VTPhysicalMemory

Deprecated.

in RTSJ 2.0; moved to package javax.realtime.memory

@Deprecated
public abstract class ScopedMemory
extends MemoryArea

Equivalent to and superseded by ScopedMemory.

Constructor Summary

Constructors

Constructor and Description
ScopedMemory(long size) Deprecated. Equivalent to ScopedMemory(long, Runnable) with the argument list (size, null).
ScopedMemory(long size, java.lang.Runnable logic) Deprecated. Creates a new ScopedMemory area with the given parameters.
ScopedMemory(SizeEstimator size) Deprecated. Equivalent to ScopedMemory(long, Runnable) with the argument list (size.getEstimate(), null).
ScopedMemory(SizeEstimator size, java.lang.Runnable logic) Deprecated. Equivalent to ScopedMemory(long, Runnable) with the argument list (size.getEstimate(), logic).

Method Summary

Modifier and Type	Method and Description
void	enter() Deprecated. 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(java.lang.Runnable logic) Deprecated. Associates this memory area with the current schedulable for the duration of the execution of the run() method of the given Runnable.
void	executeInArea(java.lang.Runnable logic) Deprecated. Executes the run method from the logic parameter using this memory area as the current allocation context.
long	getMaximumSize() Deprecated. Gets the maximum size this memory area can attain.
java.lang.Object	getPortal() Deprecated. Obtains a reference to the portal object in this instance of ScopedMemory.
int	getReferenceCount() Deprecated. Returns the reference count of this ScopedMemory.
void	join() Deprecated. Waits until the reference count of this ScopedMemory goes down to zero.
void	join(HighResolutionTime<?> time) Deprecated. Waits at most until the time designated by the time parameter for the reference count of this ScopedMemory to drop to zero.
void	joinAndEnter() Deprecated. 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) Deprecated. 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(java.lang.Runnable logic) Deprecated. 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(java.lang.Runnable logic, HighResolutionTime<?> time) Deprecated. In the error-free case, joinAndEnter combines join();enter(); such that no enter() from another schedulable can intervene between the two method invocations.
java.lang.Object	newArray(java.lang.Class<?> type, int number) Deprecated. Allocates an array of the given type in this memory area.
<T> T	newInstance(java.lang.Class<T> type) Deprecated. Allocates an object in this memory area.
<T> T	newInstance(java.lang.reflect.Constructor<T> c, java.lang.Object[] args) Deprecated. Allocates an object in this memory area.
void	setPortal(java.lang.Object object) Deprecated. Sets the portal object of the memory area represented by this instance of ScopedMemory to the given object.
java.lang.String	toString() Deprecated. 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, memoryConsumed, memoryRemaining, newArrayInArea, 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,
                    java.lang.Runnable logic)

Deprecated.

Creates a new ScopedMemory area with the given parameters.

Parameters:

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

Throws:

java.lang.IllegalArgumentException - when size is less than zero.

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

StaticOutOfMemoryError - when there is insufficient memory for the ScopedMemory object or for its allocation area in its backing store.

ScopedMemory

public ScopedMemory(SizeEstimator size,
                    java.lang.Runnable logic)

Deprecated.

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

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.

Throws:

java.lang.IllegalArgumentException - when size is null, or size.getEstimate() is negative.

StaticOutOfMemoryError - when there is insufficient memory for the ScopedMemory object or for its allocation area in its backing store.

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

ScopedMemory

public ScopedMemory(long size)

Deprecated.

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

Parameters:

size - of the new ScopedMemory area in bytes.

Throws:

java.lang.IllegalArgumentException - when size is less than zero.

StaticOutOfMemoryError - when there is insufficient memory for the ScopedMemory object or for its allocation area in its backing store.

ScopedMemory

public ScopedMemory(SizeEstimator size)

Deprecated.

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

Parameters:

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

Throws:

java.lang.IllegalArgumentException - when size is null, or size.getEstimate() is negative.

StaticOutOfMemoryError - when there is insufficient memory for the ScopedMemory object or for its allocation area in its backing store.

Method Detail

enter

public void enter()

Deprecated.

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(java.lang.Runnable)) 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.

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

java.lang.IllegalArgumentException

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(java.lang.Runnable logic)

Deprecated.

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

Overrides:

enter in class MemoryArea

Parameters:

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

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.

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

java.lang.IllegalArgumentException

executeInArea

public void executeInArea(java.lang.Runnable logic)

Deprecated.

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

Parameters:

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

Throws:

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

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

java.lang.IllegalArgumentException - when the caller is a schedulable and logic is null.

getMaximumSize

public long getMaximumSize()

Deprecated.

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.

Returns:

the maximum size attainable.

getPortal

public java.lang.Object getPortal()

Deprecated.

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.

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.

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.

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

getReferenceCount

public int getReferenceCount()

Deprecated.

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 java.lang.InterruptedException

Deprecated.

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

Throws:

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

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

join

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

Deprecated.

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.

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.

Throws:

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

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

java.lang.IllegalArgumentException - when the caller is a schedulable and time is null.

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

joinAndEnter

public void joinAndEnter()
                  throws java.lang.InterruptedException

Deprecated.

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

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

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

java.lang.IllegalArgumentException - 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 java.lang.InterruptedException

Deprecated.

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

Parameters:

time - The time that bounds the wait.

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.

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

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

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

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

joinAndEnter

public void joinAndEnter(java.lang.Runnable logic)
                  throws java.lang.InterruptedException

Deprecated.

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

Parameters:

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

Throws:

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

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

java.lang.IllegalArgumentException - when the caller is a schedulable and logic is null.

joinAndEnter

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

Deprecated.

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

Parameters:

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

time - The time that bounds the wait.

Throws:

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

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

java.lang.IllegalArgumentException - when the caller is a schedulable and time or logic is null.

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

newArray

public java.lang.Object newArray(java.lang.Class<?> type,
                                 int number)

Deprecated.

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

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

StaticOutOfMemoryError - when space in the memory area is exhausted.

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

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

newInstance

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

Deprecated.

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

Overrides:

newInstance in class MemoryArea

Type Parameters:

T - The type of the created object

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

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

StaticOutOfMemoryError - when space in the memory area is exhausted.

java.lang.InstantiationException - when the specified class object could not be instantiated. Possible causes are it is an interface, it is abstract, or it is an array.

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

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

newInstance

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

Deprecated.

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

Overrides:

newInstance in class MemoryArea

Type Parameters:

T - The type of the created object

Parameters:

c - TThe 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.IllegalAccessException - when the class or initializer is inaccessible under Java access control.

java.lang.InstantiationException - when the specified class object could not be instantiated. Possible causes are it is an interface, it is abstract, it is an array.

StaticOutOfMemoryError - when space in the memory area is exhausted.

java.lang.IllegalArgumentException

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

java.lang.reflect.InvocationTargetException - when the underlying constructor throws an exception.

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

setPortal

public void setPortal(java.lang.Object object)

Deprecated.

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.

Parameters:

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

Throws:

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

toString

public java.lang.String toString()

Deprecated.

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 java.lang.Object

Returns:

The string representation