javax.realtime.memory

Class ScopedMemory

java.lang.Object

javax.realtime.MemoryArea

javax.realtime.memory.ScopedMemory

Direct Known Subclasses:

LTMemory, PinnableMemory, StackedMemory

public abstract class ScopedMemory
extends MemoryArea

ScopedMemory is the abstract base class of all classes dealing with representations of memory spaces which have a limited lifetime. In general, objects allocated in scoped memory are freed when, and only when, no schedulable has access to the objects in the scoped memory.

A ScopedMemory area is a connection to a particular region of memory and reflects the current status of that memory. The object does not necessarily contain direct references to the region of memory. That is implementation dependent.

When a ScopedMemory area is instantiated, the object itself is allocated from the current memory allocation context, but the memory space that object represents (its backing store) is allocated from memory that is not otherwise directly visible to Java code; e.g., it might be allocated with the C malloc function. This backing store behaves effectively as if it were allocated when the associated scoped memory object is constructed and freed at that scoped memory object's finalization.

The enter() method of ScopedMemory is one mechanism used to make a memory area the current allocation context. The other mechanism for activating a memory area is making it the initial memory area for a realtime thread or async event handler. Entry into the scope is accomplished, for example, by calling the method:

      public void enter(Runnable logic)
 

where logic is an instance of Runnable whose run() method represents the entry point of the code that will run in the new scope. Exit from the scope occurs between the time the runnable.run() method completes and the time control returns from the enter method. By default, allocations of objects within runnable.run() are taken from the backing store of the ScopedMemory.

ScopedMemory is an abstract class, but all specified methods include implementations. The responsibilities of MemoryArea, ScopedMemory and the classes that extend ScopedMemory are not specified. Application code should not extend ScopedMemory without detailed knowledge of its implementation. since RTSJ 2.0, moved from javax.realtime.

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.
boolean	enter(java.util.function.BooleanSupplier logic) Same as enter(Runnable) except that the executed method is called get and a boolean is returned.
double	enter(java.util.function.DoubleSupplier logic) Same as enter(Runnable) except that the executed method is called get and a double is returned.
int	enter(java.util.function.IntSupplier logic) Same as enter(Runnable) except that the executed method is called get and an int is returned.
long	enter(java.util.function.LongSupplier logic) Same as enter(Runnable) except that the executed method is called get and a long is returned.
void	enter(java.lang.Runnable logic) Associates this memory area with the current schedulable for the duration of the execution of the run() method of the given Runnable.
<T> T	enter(java.util.function.Supplier<T> logic) Same as enter(Runnable) except that the executed method is called get and an object is returned.
boolean	executeInArea(java.util.function.BooleanSupplier logic) Same as executeInArea(Runnable) except that the executed method is called get and a boolean is returned.
double	executeInArea(java.util.function.DoubleSupplier logic) Same as executeInArea(Runnable) except that the executed method is called get and a double is returned.
int	executeInArea(java.util.function.IntSupplier logic) Same as executeInArea(Runnable) except that the executed method is called get and an int is returned.
long	executeInArea(java.util.function.LongSupplier logic) Same as executeInArea(Runnable) except that the executed method is called get and a long is returned.
void	executeInArea(java.lang.Runnable logic) Executes the run method from the logic parameter using this memory area as the current allocation context.
<T> T	executeInArea(java.util.function.Supplier<T> logic) Same as executeInArea(Runnable) except that the executed method is called get and an object is returned.
protected void	finalize() Since there is no specified way to release the memory of a memory area explicitly, this is done by its finalize method.
MemoryArea	getParent() Returns a reference to this scope's parent scope (e.g., its parent in the single-parent-rule tree).
java.lang.Object	getPortal() Returns a reference to the portal object in this instance of ScopedMemory.
int	getReferenceCount() Returns the reference count of this ScopedMemory.
static long	globalBackingStoreConsumed() Determines the amount of memory consumed by exisiting scoped memories from the global backing store.
static long	globalBackingStoreRemaining() Determines the amount of memory remaining for allocation to new scoped memories in the backing store of this scoped memory.
static long	globalBackingStoreSize() Determines the total amount of memory in the global backing store.
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.
boolean	joinAndEnter(java.util.function.BooleanSupplier logic) Same as joinAndEnter(Runnable) except that the executed method is called get and a boolean is returned.
boolean	joinAndEnter(java.util.function.BooleanSupplier logic, HighResolutionTime<?> time) Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and a boolean is returned.
double	joinAndEnter(java.util.function.DoubleSupplier logic) Same as joinAndEnter(Runnable) except that the executed method is called get and a double is returned.
double	joinAndEnter(java.util.function.DoubleSupplier logic, HighResolutionTime<?> time) Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and a double is returned.
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.
int	joinAndEnter(java.util.function.IntSupplier logic) Same as joinAndEnter(Runnable) except that the executed method is called get and an int is returned.
int	joinAndEnter(java.util.function.IntSupplier logic, HighResolutionTime<?> time) Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and an int is returned.
long	joinAndEnter(java.util.function.LongSupplier logic) Same as joinAndEnter(Runnable) except that the executed method is called get and a long is returned.
long	joinAndEnter(java.util.function.LongSupplier logic, HighResolutionTime<?> time) Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and a long is returned.
void	joinAndEnter(java.lang.Runnable logic) In the error-free case, joinAndEnter combines join(); and enter(); such that no enter() from another schedulable can intervene between the two method invocations.
void	joinAndEnter(java.lang.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.
<P> P	joinAndEnter(java.util.function.Supplier<P> logic, HighResolutionTime<?> time) Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and an object is returned.
<T> T	joinAndEnter(java.util.function.Supplier<T> logic) Same as joinAndEnter(Runnable) except that the executed method is called get and an object is returned.
java.lang.Object	newArray(java.lang.Class<?> type, int number) Allocates an array of the given type in this memory area.
<T> T	newInstance(java.lang.Class<T> type) Allocates an object in this memory area.
<T> T	newInstance(java.lang.reflect.Constructor<T> c, java.lang.Object[] args) Allocates an object in this memory area.
void	setPortal(java.lang.Object object) Sets the portal object of the memory area represented by this instance of ScopedMemory to the given object.
java.lang.String	toString() Returns a user-friendly representation of this ScopedMemory of the form <class-name>@<num> where <class-name> is the name of the class, e.g.
void	visitNestedScopes(java.util.function.Consumer<ScopedMemory> visitor) A means of accessing all live nested scoped memories parented in this scoped memory, even those to which no reference exists, such a PinnableMemory that is pinned or another javax.realtime.memory.ScopedMemory that contains a Schedulable.
static void	visitScopeRoots(java.util.function.Consumer<ScopedMemory> visitor) A means of accessing all live scoped memories whose parent is a perennial memory area, even those to which no reference exists, such a PinnableMemory that is pinned or another javax.realtime.memory.ScopedMemory that contains a Schedulable.

Methods inherited from class javax.realtime.MemoryArea

getMemoryArea, mayHoldReferenceTo, mayHoldReferenceTo, memoryConsumed, memoryRemaining, newArrayInArea, size

Methods inherited from class java.lang.Object

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

Method Detail

globalBackingStoreSize

public static long globalBackingStoreSize()

Determines the total amount of memory in the global backing store.

Returns:

the total amount of global backing store in bytes.

Since:

RTSJ 2.0

globalBackingStoreRemaining

public static long globalBackingStoreRemaining()

Determines the amount of memory remaining for allocation to new scoped memories in the backing store of this scoped memory.

Returns:

the amount of global backing store remaing in bytes.

Since:

RTSJ 2.0

globalBackingStoreConsumed

public static long globalBackingStoreConsumed()

Determines the amount of memory consumed by exisiting scoped memories from the global backing store.

Returns:

the amount of backing store available in bytes.

Since:

RTSJ 2.0

visitScopeRoots

public static void visitScopeRoots(java.util.function.Consumer<ScopedMemory> visitor)
                            throws StaticIllegalArgumentException,
                                   ForEachTerminationException

A means of accessing all live scoped memories whose parent is a perennial memory area, even those to which no reference exists, such a PinnableMemory that is pinned or another javax.realtime.memory.ScopedMemory that contains a Schedulable. The set may be concurrently modified by other tasks, but the view seen by the visitor may not be updated to reflect those changes. The following is guaranteed even when the set is disturbed by other tasks:

• the visitor shall visit no member more than once,
• it shall visit only scopes that were a member of the set at some time during the enumeration of the set, and
• it shall visit all the scopes that are not deleted during the execution of the visitor.

The visitor's accept method is called on all live roots scopes, so long as the visitor does not throw ForEachTerminationException. When that is thrown, the visit terminates. A closure could be used to capture the last element visited.

When execution of the visitor's accept method is terminated abruptly by throwing an exception, then execution of visitScopedChildren also terminates abruptly by throwing the same exception.

Parameters:

visitor - Determines the action to be performed on each of the children scopes.

Throws:

StaticIllegalArgumentException - when visitor is null.

ForEachTerminationException - when the traversal ends prematurely.

StaticSecurityException - when the application does not have permissions to access visit root scopes.

Since:

RTSJ 2.0

enter

public void enter()
           throws ScopedCycleException,
                  ThrowBoundaryError,
                  IllegalTaskStateException,
                  StaticIllegalArgumentException,
                  MemoryAccessError

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

IllegalTaskStateException - when the execution 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 execution context that triggered finalization. This would include the scope containing the execution context, and the scope (if any) containing the scope containing execution context.

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(java.lang.Runnable logic)
           throws ScopedCycleException,
                  ThrowBoundaryError,
                  IllegalTaskStateException,
                  StaticIllegalArgumentException

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.

IllegalTaskStateException - when the execution 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 task that triggered finalization. This would include the scope containing the task, and the scope (if any) containing the scope containing task.

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

enter

public <T> T enter(java.util.function.Supplier<T> logic)
            throws ScopedCycleException,
                   ThrowBoundaryError,
                   IllegalTaskStateException,
                   StaticIllegalArgumentException

Same as enter(Runnable) except that the executed method is called get and an object is returned.

Overrides:

enter in class MemoryArea

Type Parameters:

T - The type of the object returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

ScopedCycleException

ThrowBoundaryError

IllegalTaskStateException

StaticIllegalArgumentException

enter

public boolean enter(java.util.function.BooleanSupplier logic)
              throws ScopedCycleException,
                     ThrowBoundaryError,
                     IllegalTaskStateException,
                     StaticIllegalArgumentException

Same as enter(Runnable) except that the executed method is called get and a boolean is returned.

Overrides:

enter in class MemoryArea

Parameters:

logic - the object whose get method will be executed.

Returns:

a result from the computation.

Throws:

ScopedCycleException

ThrowBoundaryError

IllegalTaskStateException

StaticIllegalArgumentException

enter

public int enter(java.util.function.IntSupplier logic)
          throws ScopedCycleException,
                 ThrowBoundaryError,
                 IllegalTaskStateException,
                 StaticIllegalArgumentException

Same as enter(Runnable) except that the executed method is called get and an int is returned.

Overrides:

enter in class MemoryArea

Parameters:

logic - the object whose get method will be executed.

Returns:

a result from the computation.

Throws:

ScopedCycleException

ThrowBoundaryError

IllegalTaskStateException

StaticIllegalArgumentException

enter

public long enter(java.util.function.LongSupplier logic)
           throws ScopedCycleException,
                  ThrowBoundaryError,
                  IllegalTaskStateException,
                  StaticIllegalArgumentException

Same as enter(Runnable) except that the executed method is called get and a long is returned.

Overrides:

enter in class MemoryArea

Parameters:

logic - the object whose get method will be executed.

Returns:

a result from the computation.

Throws:

ScopedCycleException

ThrowBoundaryError

IllegalTaskStateException

StaticIllegalArgumentException

enter

public double enter(java.util.function.DoubleSupplier logic)
             throws ScopedCycleException,
                    ThrowBoundaryError,
                    IllegalTaskStateException,
                    StaticIllegalArgumentException

Same as enter(Runnable) except that the executed method is called get and a double is returned.

Overrides:

enter in class MemoryArea

Parameters:

logic - the object whose get method will be executed.

Returns:

a result from the computation.

Throws:

ScopedCycleException

ThrowBoundaryError

IllegalTaskStateException

StaticIllegalArgumentException

executeInArea

public void executeInArea(java.lang.Runnable logic)
                   throws IllegalTaskStateException,
                          StaticIllegalArgumentException,
                          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

Parameters:

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

Throws:

IllegalTaskStateException - when the execution context is not an instance of Schedulable.

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

StaticIllegalArgumentException - when the execution context is an instance of Schedulable schedulable and logic is null.

executeInArea

public <T> T executeInArea(java.util.function.Supplier<T> logic)
                    throws IllegalTaskStateException,
                           StaticIllegalArgumentException,
                           InaccessibleAreaException

Same as executeInArea(Runnable) except that the executed method is called get and an object is returned.

Overrides:

executeInArea in class MemoryArea

Type Parameters:

T - the type of the returned object.

Parameters:

logic - the object whose get method will be executed.

Returns:

a result from the computation.

Throws:

IllegalTaskStateException

StaticIllegalArgumentException

InaccessibleAreaException

executeInArea

public boolean executeInArea(java.util.function.BooleanSupplier logic)
                      throws IllegalTaskStateException,
                             StaticIllegalArgumentException,
                             InaccessibleAreaException

Same as executeInArea(Runnable) except that the executed method is called get and a boolean is returned.

Overrides:

executeInArea in class MemoryArea

Parameters:

logic - the object whose get method will be executed.

Returns:

a result from the computation.

Throws:

IllegalTaskStateException

StaticIllegalArgumentException

InaccessibleAreaException

executeInArea

public int executeInArea(java.util.function.IntSupplier logic)
                  throws IllegalTaskStateException,
                         StaticIllegalArgumentException,
                         InaccessibleAreaException

Same as executeInArea(Runnable) except that the executed method is called get and an int is returned.

Overrides:

executeInArea in class MemoryArea

Parameters:

logic - the object whose get method will be executed.

Returns:

a result from the computation.

Throws:

IllegalTaskStateException

StaticIllegalArgumentException

InaccessibleAreaException

executeInArea

public long executeInArea(java.util.function.LongSupplier logic)
                   throws IllegalTaskStateException,
                          StaticIllegalArgumentException,
                          InaccessibleAreaException

Same as executeInArea(Runnable) except that the executed method is called get and a long is returned.

Overrides:

executeInArea in class MemoryArea

Parameters:

logic - the object whose get method will be executed.

Returns:

a result from the computation.

Throws:

IllegalTaskStateException

StaticIllegalArgumentException

InaccessibleAreaException

executeInArea

public double executeInArea(java.util.function.DoubleSupplier logic)
                     throws IllegalTaskStateException,
                            StaticIllegalArgumentException,
                            InaccessibleAreaException

Same as executeInArea(Runnable) except that the executed method is called get and a double is returned.

Overrides:

executeInArea in class MemoryArea

Parameters:

logic - the object whose get method will be executed.

Returns:

a result from the computation.

Throws:

IllegalTaskStateException

StaticIllegalArgumentException

InaccessibleAreaException

getPortal

public java.lang.Object getPortal()
                           throws IllegalAssignmentError,
                                  IllegalTaskStateException

Returns 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 the object is allocated in a more deeply nested scoped memory than the current allocation context or not on the caller's scope stack.

IllegalTaskStateException - when the execution context is not an instance of Schedulable.

getReferenceCount

public final int getReferenceCount()

Returns the reference count of this ScopedMemory.

Note that a reference count of zero 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

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.

IllegalTaskStateException - when the execution context is not an instance of Schedulable.

join

public void join(HighResolutionTime<?> time)
          throws java.lang.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.

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 (or a member of the RationalTime subclass of RelativeTime) 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.

IllegalTaskStateException - when the execution context is not an instance of Schedulable.

StaticIllegalArgumentException - when the execution context is a schedulable and time is null.

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

joinAndEnter

public void joinAndEnter()
                  throws java.lang.InterruptedException,
                         IllegalTaskStateException,
                         ThrowBoundaryError,
                         ScopedCycleException,
                         StaticIllegalArgumentException,
                         MemoryAccessError

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 enters the ScopedMemory and executes 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:

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

IllegalTaskStateException - when the execution 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 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 this invocation would break the single parent rule.

StaticIllegalArgumentException - when the execution context 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,
                         IllegalTaskStateException,
                         ThrowBoundaryError,
                         ScopedCycleException,
                         StaticIllegalArgumentException,
                         StaticUnsupportedOperationException,
                         MemoryAccessError

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.

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.

IllegalTaskStateException - when the execution 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 task that triggered finalization. This would include the scope containing the task, and the scope (if any) containing the scope containing the task.

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

StaticIllegalArgumentException - when the execution context is a schedulable, and time is null or no non-null logic value was supplied to the memory area's constructor.

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

MemoryAccessError - when 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,
                         IllegalTaskStateException,
                         ThrowBoundaryError,
                         ScopedCycleException,
                         StaticIllegalArgumentException,
                         MemoryAccessError

In the error-free case, joinAndEnter combines join(); and 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, 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.

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.

IllegalTaskStateException - when the execution 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 task that triggered finalization. This would include the scope containing the task, and the scope (if any) containing the scope containing the task.

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.

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

StaticIllegalArgumentException - when the execution context is a schedulable and logic is null.

MemoryAccessError

joinAndEnter

public <T> T joinAndEnter(java.util.function.Supplier<T> logic)
                   throws java.lang.InterruptedException,
                          IllegalTaskStateException,
                          ThrowBoundaryError,
                          ScopedCycleException,
                          StaticIllegalArgumentException,
                          MemoryAccessError

Same as joinAndEnter(Runnable) except that the executed method is called get and an object is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

java.lang.InterruptedException

IllegalTaskStateException

ThrowBoundaryError

ScopedCycleException

StaticIllegalArgumentException

MemoryAccessError

Since:

RTSJ 2.0

joinAndEnter

public boolean joinAndEnter(java.util.function.BooleanSupplier logic)
                     throws java.lang.InterruptedException,
                            IllegalTaskStateException,
                            ThrowBoundaryError,
                            ScopedCycleException,
                            StaticIllegalArgumentException,
                            MemoryAccessError

Same as joinAndEnter(Runnable) except that the executed method is called get and a boolean is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

java.lang.InterruptedException

IllegalTaskStateException

ThrowBoundaryError

ScopedCycleException

StaticIllegalArgumentException

MemoryAccessError

Since:

RTSJ 2.0

joinAndEnter

public int joinAndEnter(java.util.function.IntSupplier logic)
                 throws java.lang.InterruptedException,
                        IllegalTaskStateException,
                        ThrowBoundaryError,
                        ScopedCycleException,
                        StaticIllegalArgumentException,
                        MemoryAccessError

Same as joinAndEnter(Runnable) except that the executed method is called get and an int is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

java.lang.InterruptedException

IllegalTaskStateException

ThrowBoundaryError

ScopedCycleException

StaticIllegalArgumentException

MemoryAccessError

Since:

RTSJ 2.0

joinAndEnter

public long joinAndEnter(java.util.function.LongSupplier logic)
                  throws java.lang.InterruptedException,
                         IllegalTaskStateException,
                         ThrowBoundaryError,
                         ScopedCycleException,
                         StaticIllegalArgumentException,
                         MemoryAccessError

Same as joinAndEnter(Runnable) except that the executed method is called get and a long is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

java.lang.InterruptedException

IllegalTaskStateException

ThrowBoundaryError

ScopedCycleException

StaticIllegalArgumentException

MemoryAccessError

Since:

RTSJ 2.0

joinAndEnter

public double joinAndEnter(java.util.function.DoubleSupplier logic)
                    throws java.lang.InterruptedException,
                           IllegalTaskStateException,
                           ThrowBoundaryError,
                           ScopedCycleException,
                           StaticIllegalArgumentException,
                           MemoryAccessError

Same as joinAndEnter(Runnable) except that the executed method is called get and a double is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

java.lang.InterruptedException

IllegalTaskStateException

ThrowBoundaryError

ScopedCycleException

StaticIllegalArgumentException

MemoryAccessError

Since:

RTSJ 2.0

joinAndEnter

public void joinAndEnter(java.lang.Runnable logic,
                         HighResolutionTime<?> time)
                  throws java.lang.InterruptedException,
                         IllegalTaskStateException,
                         ThrowBoundaryError,
                         ScopedCycleException,
                         StaticIllegalArgumentException,
                         StaticUnsupportedOperationException,
                         MemoryAccessError

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

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

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.

IllegalTaskStateException - when the execution 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 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 a IllegalAssignmentError, so the JVM cannot be permitted to deliver the exception. The ThrowBoundaryError is preallocated and saves information about the exception it replaces.

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

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

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

MemoryAccessError

joinAndEnter

public <P> P joinAndEnter(java.util.function.Supplier<P> logic,
                          HighResolutionTime<?> time)
                   throws java.lang.InterruptedException,
                          IllegalTaskStateException,
                          ThrowBoundaryError,
                          ScopedCycleException,
                          StaticIllegalArgumentException,
                          StaticUnsupportedOperationException,
                          MemoryAccessError

Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and an object is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

java.lang.InterruptedException

IllegalTaskStateException

ThrowBoundaryError

ScopedCycleException

StaticIllegalArgumentException

StaticUnsupportedOperationException

MemoryAccessError

Since:

RTSJ 2.0

joinAndEnter

public boolean joinAndEnter(java.util.function.BooleanSupplier logic,
                            HighResolutionTime<?> time)
                     throws java.lang.InterruptedException,
                            IllegalTaskStateException,
                            ThrowBoundaryError,
                            ScopedCycleException,
                            StaticIllegalArgumentException,
                            StaticUnsupportedOperationException,
                            MemoryAccessError

Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and a boolean is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

java.lang.InterruptedException

IllegalTaskStateException

ThrowBoundaryError

ScopedCycleException

StaticIllegalArgumentException

StaticUnsupportedOperationException

MemoryAccessError

Since:

RTSJ 2.0

joinAndEnter

public int joinAndEnter(java.util.function.IntSupplier logic,
                        HighResolutionTime<?> time)
                 throws java.lang.InterruptedException,
                        IllegalTaskStateException,
                        ThrowBoundaryError,
                        ScopedCycleException,
                        StaticIllegalArgumentException,
                        StaticUnsupportedOperationException,
                        MemoryAccessError

Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and an int is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

java.lang.InterruptedException

IllegalTaskStateException

ThrowBoundaryError

ScopedCycleException

StaticIllegalArgumentException

StaticUnsupportedOperationException

MemoryAccessError

Since:

RTSJ 2.0

joinAndEnter

public long joinAndEnter(java.util.function.LongSupplier logic,
                         HighResolutionTime<?> time)
                  throws java.lang.InterruptedException,
                         IllegalTaskStateException,
                         ThrowBoundaryError,
                         ScopedCycleException,
                         StaticIllegalArgumentException,
                         StaticUnsupportedOperationException,
                         MemoryAccessError

Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and a long is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

java.lang.InterruptedException

IllegalTaskStateException

ThrowBoundaryError

ScopedCycleException

StaticIllegalArgumentException

StaticUnsupportedOperationException

MemoryAccessError

Since:

RTSJ 2.0

joinAndEnter

public double joinAndEnter(java.util.function.DoubleSupplier logic,
                           HighResolutionTime<?> time)
                    throws java.lang.InterruptedException,
                           IllegalTaskStateException,
                           ThrowBoundaryError,
                           ScopedCycleException,
                           StaticIllegalArgumentException,
                           StaticUnsupportedOperationException,
                           MemoryAccessError

Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and a double is returned.

Parameters:

logic - The object whose get method will be executed.

Returns:

a result from the computation.

Throws:

java.lang.InterruptedException

IllegalTaskStateException

ThrowBoundaryError

ScopedCycleException

StaticIllegalArgumentException

StaticUnsupportedOperationException

MemoryAccessError

Since:

RTSJ 2.0

getParent

public MemoryArea getParent()

Returns a reference to this scope's parent scope (e.g., its parent in the single-parent-rule tree).

Returns:

a reference to the next outer scoped memory region on the caller's scope stack.

• When there is no outer scoped memory and the primordial parent is heap memory, returns a reference to this.
• When there is no outer scoped memory and the primordial parent is immortal, or when this is unreferenced and unpinned, returns null

Problem. The single-parent tree is RTT-independent except for the primordial scope. The type of the primordial scope is RTT-dependent. What should we do about that? When called from a RTT that has entered this, the above rules make some sense, but what if the caller has not even entered the scope, should we throw an exception? Or just return null? I think the right solution is to return this whatever the type of the primordial scope. The app can then know that null means the scope is not pinned and not referenced, and this means the parent is either heap or immortal. At that point, the app can learn what it wants to know by just finding what memory area contains the scope object.

Since:

RTSJ 2.0

visitNestedScopes

public void visitNestedScopes(java.util.function.Consumer<ScopedMemory> visitor)
                       throws StaticIllegalArgumentException,
                              ForEachTerminationException

A means of accessing all live nested scoped memories parented in this scoped memory, even those to which no reference exists, such a PinnableMemory that is pinned or another javax.realtime.memory.ScopedMemory that contains a Schedulable. It has the same semantics as the method visitScopeRoots(java.util.function.Consumer<javax.realtime.memory.ScopedMemory>), except for the following:

• what scoped memories are visited,
• the memory area must be reachable from the current scope stack, and
• there is not security manager check.

Parameters:

visitor - Determines the action to be performed on each of the children scopes.

Throws:

StaticIllegalArgumentException - when visitor is null.

ForEachTerminationException - when the traversal ends prematurely.

Since:

RTSJ 2.0

newArray

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

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:

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

StaticOutOfMemoryError - when space in the memory area is exhausted.

IllegalTaskStateException - when the execution context is 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,
                         StaticIllegalArgumentException,
                         java.lang.ExceptionInInitializerError,
                         StaticOutOfMemoryError,
                         java.lang.InstantiationException,
                         IllegalTaskStateException,
                         InaccessibleAreaException

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.

StaticIllegalArgumentException - when type is null.

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.

IllegalTaskStateException - when the execution context is 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

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

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

IllegalTaskStateException - when the execution context is 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)
               throws IllegalTaskStateException,
                      IllegalAssignmentError,
                      InaccessibleAreaException

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:

IllegalTaskStateException - when the execution context is not an instance of Schedulable.

IllegalAssignmentError - when the execution context is an instance of Schedulable, and object is not allocated in this scoped memory instance and not null.

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

finalize

protected final void finalize()
                       throws java.lang.Throwable

Since there is no specified way to release the memory of a memory area explicitly, this is done by its finalize method.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.InternalError - when this is currently in use (i.e., it has a non-zero enter count.)

java.lang.Throwable

toString

public java.lang.String toString()

Returns a user-friendly representation of this ScopedMemory of the form <class-name>@<num> where <class-name> is the name of the class, e.g. javax.realtime.memory.ScopedMemory, and <num> is a number that uniquely identifies this scoped memory area.

Overrides:

toString in class java.lang.Object

Returns:

the string representation