ScopedMemory (aicas JamaicaVM API)

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 object 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. In JamaicaVM, application code is not permitted to create instances of user-defined direct subclasses of ScopedMemory.
Since:

RTSJ 2.0

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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(BooleanSupplier logic)` Same as `MemoryArea.enter(Runnable)` except that the executed method is called `getAsBoolean()` and a boolean is returned.
`double`	`enter(DoubleSupplier logic)` Same as `MemoryArea.enter(Runnable)` except that the executed method is called `getAsDouble()` and a double is returned.
`int`	`enter(IntSupplier logic)` Same as `MemoryArea.enter(Runnable)` except that the executed method is called `getAsInt()` and an int is returned.
`long`	`enter(LongSupplier logic)` Same as `MemoryArea.enter(Runnable)` except that the executed method is called `getAsLong()` and a long is returned.
`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`.
`<T> T`	`enter(Supplier<T> logic)` Same as `MemoryArea.enter(Runnable)` except that the executed method is called `get()` and an object is returned.
`boolean`	`executeInArea(BooleanSupplier logic)` Executes the run method from the `logic` parameter using this memory area as the current allocation context.
`double`	`executeInArea(DoubleSupplier logic)` Executes the run method from the `logic` parameter using this memory area as the current allocation context.
`int`	`executeInArea(IntSupplier logic)` Executes the run method from the `logic` parameter using this memory area as the current allocation context.
`long`	`executeInArea(LongSupplier logic)` Executes the run method from the `logic` parameter using this memory area as the current allocation context.
`void`	`executeInArea(Runnable logic)` Executes the run method from the `logic` parameter using this memory area as the current allocation context.
`<T> T`	`executeInArea(Supplier<T> logic)` Executes the run method from the `logic` parameter using this memory area as the current allocation context.
`protected void`	`finalize()` Synchronized helper for finalize to free the memory of this ScopedMemory.
`MemoryArea`	`getParent()` Gets the parent memory area when there is a parent set.
`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()`
`static long`	`globalBackingStoreRemaining()`
`static long`	`globalBackingStoreSize()`
`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(BooleanSupplier logic)` Same as `joinAndEnter(Runnable)` except that the executed method is called `get` and a `boolean` is returned.
`boolean`	`joinAndEnter(BooleanSupplier logic, HighResolutionTime<?> time)` Same as `joinAndEnter(Runnable, HighResolutionTime)` except that the executed method is called `get` and a `boolean` is returned.
`double`	`joinAndEnter(DoubleSupplier logic)` Same as `joinAndEnter(Runnable)` except that the executed method is called `get` and a `double` is returned.
`double`	`joinAndEnter(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(IntSupplier logic)` Same as `joinAndEnter(Runnable)` except that the executed method is called `get` and an `int` is returned.
`int`	`joinAndEnter(IntSupplier logic, HighResolutionTime<?> time)` Same as `joinAndEnter(Runnable, HighResolutionTime)` except that the executed method is called `get` and an `int` is returned.
`long`	`joinAndEnter(LongSupplier logic)` Same as `joinAndEnter(Runnable)` except that the executed method is called `get` and a `long` is returned.
`long`	`joinAndEnter(LongSupplier logic, HighResolutionTime<?> time)` Same as `joinAndEnter(Runnable, HighResolutionTime)` except that the executed method is called `get` and a `long` is returned.
`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.
`<P> P`	`joinAndEnter(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(Supplier<T> logic)` Same as `joinAndEnter(Runnable)` except that the executed method is called `get` and an object is returned.
`boolean`	`mayHoldReferenceTo()` Determines whether an object `A` allocated in the memory area represented by `this` can hold a reference to an object `B` allocated in the current memory area.
`boolean`	`mayHoldReferenceTo(Object value)` Determines whether an object allocated in the memory area represented by `this` can hold a reference to the object `value`.
`void`	`setPortal(Object object)` Sets the portal object of the memory area represented by this instance of `ScopedMemory` to the given object.
`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(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(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, memoryConsumed, memoryRemaining, newArray, newArrayInArea, newInstance, newInstance, size

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - globalBackingStoreSize
```
public static long globalBackingStoreSize()
```
  - globalBackingStoreConsumed
```
public static long globalBackingStoreConsumed()
```
  - globalBackingStoreRemaining
```
public static long globalBackingStoreRemaining()
```
  - visitScopeRoots
```
public static void visitScopeRoots(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.
    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.
    
    Parameters:
    
    visitor - Determines the action to be performed on each of the children scopes.
    
    Since:
    
    RTSJ 2.0
  - mayHoldReferenceTo
```
public boolean mayHoldReferenceTo()
```
    Description copied from class: MemoryArea
    
    Determines whether an object A allocated in the memory area represented by this can hold a reference to an object B allocated in the current memory area.
    
    Overrides:
    
    mayHoldReferenceTo in class MemoryArea
    
    Returns:
    
    true only when the current memory area is also an instance of PerennialMemory.
  - mayHoldReferenceTo
```
public boolean mayHoldReferenceTo(Object value)
```
    Description copied from class: MemoryArea
    
    Determines whether an object allocated in the memory area represented by this can hold a reference to the object value.
    
    Overrides:
    
    mayHoldReferenceTo in class MemoryArea
    
    Parameters:
    
    value - The object to test.
    
    Returns:
    
    does not return at the moment.
  - enter
```
public void enter()
           throws ScopedCycleException
```
    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 may not 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(Runnable logic)
           throws ScopedCycleException
```
    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
    
    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 may not 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.
    
    Parameters:
    
    logic - The Runnable object whose run() method should be invoked.
  - enter
```
public boolean enter(BooleanSupplier logic)
              throws ScopedCycleException
```
    Description copied from class: MemoryArea
    
    Same as MemoryArea.enter(Runnable) except that the executed method is called getAsBoolean() and a boolean is returned.
    
    Overrides:
    
    enter in class MemoryArea
    
    Throws:
    
    ScopedCycleException
    
    Parameters:
    
    logic - The object whose getAsboolean() method is to be executed.
    
    Returns:
    
    the value return by the getAsBoolean() method.
  - enter
```
public double enter(DoubleSupplier logic)
             throws ScopedCycleException
```
    Description copied from class: MemoryArea
    
    Same as MemoryArea.enter(Runnable) except that the executed method is called getAsDouble() and a double is returned.
    
    Overrides:
    
    enter in class MemoryArea
    
    Throws:
    
    ScopedCycleException
    
    Parameters:
    
    logic - The object whose getAsDouble() method is to be executed.
    
    Returns:
    
    the value return by the getAsDouble() method.
  - enter
```
public int enter(IntSupplier logic)
          throws ScopedCycleException
```
    Description copied from class: MemoryArea
    
    Same as MemoryArea.enter(Runnable) except that the executed method is called getAsInt() and an int is returned.
    
    Overrides:
    
    enter in class MemoryArea
    
    Throws:
    
    ScopedCycleException
    
    Parameters:
    
    logic - The object whose getAsInt() method is to be executed.
    
    Returns:
    
    the value return by the getAsInt() method.
  - enter
```
public long enter(LongSupplier logic)
           throws ScopedCycleException
```
    Description copied from class: MemoryArea
    
    Same as MemoryArea.enter(Runnable) except that the executed method is called getAsLong() and a long is returned.
    
    Overrides:
    
    enter in class MemoryArea
    
    Throws:
    
    ScopedCycleException
    
    Parameters:
    
    logic - The object whose getAsLong() method is to be executed.
    
    Returns:
    
    the value return by the getAsLong() method.
  - enter
```
public <T> T enter(Supplier<T> logic)
            throws ScopedCycleException
```
    Description copied from class: MemoryArea
    
    Same as MemoryArea.enter(Runnable) except that the executed method is called get() and an object is returned. The The get() method must ensure that the returned object is allocated outside the area, when the area is not a PerennialMemory.
    
    Overrides:
    
    enter in class MemoryArea
    
    Throws:
    
    ScopedCycleException
    
    Parameters:
    
    logic - The object whose get() method is to be executed.
    
    Returns:
    
    the value return by the get() method.
  - getPortal
```
public Object getPortal()
                 throws MemoryAccessError,
                        IllegalAssignmentError
```
    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.
    
    Throws:
    
    IllegalAssignmentError - when a reference to the portal object may not 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.
    
    MemoryAccessError
    
    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 object)
```
    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 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.
    
    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.
  - 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.
  - getParent
```
public MemoryArea getParent()
```
    Gets the parent memory area when there is a parent set. It is set when a thread or handler is created.
    
    Returns:
    
    null or the parent scope
  - toString
```
public 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 Object
    
    Returns:
    
    the string representation
  - 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.
    
    IllegalTaskStateException - when the execution context is not an instance of Schedulable.
    
    StaticIllegalArgumentException - when the execution context 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 (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.
  - 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.
    
    IllegalTaskStateException - when the execution context is not an instance of Schedulable.
  - 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 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:
    
    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 may not 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 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 may not 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.
    
    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.
    
    UnsupportedOperationException - 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.
    
    Parameters:
    
    time - The time that bounds the wait.
  - joinAndEnter
```
public void joinAndEnter(Runnable logic)
                  throws InterruptedException,
                         StaticIllegalArgumentException,
                         IllegalTaskStateException,
                         ThrowBoundaryError,
                         ScopedCycleException,
                         StaticIllegalStateException
```
    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, 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.
    
    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 may not 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.
    
    StaticIllegalStateException
    
    Parameters:
    
    logic - The Runnable object which contains the code to execute.
  - joinAndEnter
```
public <T> T joinAndEnter(Supplier<T> logic)
                   throws InterruptedException
```
    Same as joinAndEnter(Runnable) except that the executed method is called get and an object is returned.
    
    Throws:
    
    InterruptedException
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    a result from the computation.
    
    Since:
    
    RTSJ 2.0
  - joinAndEnter
```
public boolean joinAndEnter(BooleanSupplier logic)
                     throws InterruptedException
```
    Same as joinAndEnter(Runnable) except that the executed method is called get and a boolean is returned.
    
    Throws:
    
    InterruptedException
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    a result from the computation.
    
    Since:
    
    RTSJ 2.0
  - joinAndEnter
```
public int joinAndEnter(IntSupplier logic)
                 throws InterruptedException
```
    Same as joinAndEnter(Runnable) except that the executed method is called get and an int is returned.
    
    Throws:
    
    InterruptedException
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    a result from the computation.
    
    Since:
    
    RTSJ 2.0
  - joinAndEnter
```
public long joinAndEnter(LongSupplier logic)
                  throws InterruptedException
```
    Same as joinAndEnter(Runnable) except that the executed method is called get and a long is returned.
    
    Throws:
    
    InterruptedException
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    a result from the computation.
    
    Since:
    
    RTSJ 2.0
  - joinAndEnter
```
public double joinAndEnter(DoubleSupplier logic)
                    throws InterruptedException
```
    Same as joinAndEnter(Runnable) except that the executed method is called get and a double is returned.
    
    Throws:
    
    InterruptedException
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    a result from the computation.
    
    Since:
    
    RTSJ 2.0
  - 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).
    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.
    
    Throws:
    
    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 may not 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.
    
    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.
  - joinAndEnter
```
public <P> P joinAndEnter(Supplier<P> logic,
                          HighResolutionTime<?> time)
                   throws InterruptedException
```
    Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and an object is returned.
    
    Throws:
    
    InterruptedException
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    a result from the computation.
    
    Since:
    
    RTSJ 2.0
  - joinAndEnter
```
public boolean joinAndEnter(BooleanSupplier logic,
                            HighResolutionTime<?> time)
                     throws InterruptedException
```
    Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and a boolean is returned.
    
    Throws:
    
    InterruptedException
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    a result from the computation.
    
    Since:
    
    RTSJ 2.0
  - joinAndEnter
```
public int joinAndEnter(IntSupplier logic,
                        HighResolutionTime<?> time)
                 throws InterruptedException
```
    Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and an int is returned.
    
    Throws:
    
    InterruptedException
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    a result from the computation.
    
    Since:
    
    RTSJ 2.0
  - joinAndEnter
```
public long joinAndEnter(LongSupplier logic,
                         HighResolutionTime<?> time)
                  throws InterruptedException
```
    Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and a long is returned.
    
    Throws:
    
    InterruptedException
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    a result from the computation.
    
    Since:
    
    RTSJ 2.0
  - joinAndEnter
```
public double joinAndEnter(DoubleSupplier logic,
                           HighResolutionTime<?> time)
                    throws InterruptedException
```
    Same as joinAndEnter(Runnable, HighResolutionTime) except that the executed method is called get and a double is returned.
    
    Throws:
    
    InterruptedException
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    a result from the computation.
    
    Since:
    
    RTSJ 2.0
  - 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:
    
    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.
    
    Parameters:
    
    logic - The runnable object whose run() method should be executed.
  - executeInArea
```
public <T> T executeInArea(Supplier<T> 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:
    
    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.
    
    Parameters:
    
    logic - The runnable object whose run() method should be executed.
    
    Returns:
    
    the value return by the get() method.
  - executeInArea
```
public int executeInArea(IntSupplier 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:
    
    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.
    
    Parameters:
    
    logic - The runnable object whose run() method should be executed.
    
    Returns:
    
    the value return by the getAsInt() method.
  - executeInArea
```
public long executeInArea(LongSupplier 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:
    
    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.
    
    Parameters:
    
    logic - The runnable object whose run() method should be executed.
    
    Returns:
    
    the value return by the getAsLong() method.
  - executeInArea
```
public double executeInArea(DoubleSupplier 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:
    
    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.
    
    Parameters:
    
    logic - The runnable object whose run() method should be executed.
    
    Returns:
    
    the value return by the getAsDouble() method.
  - executeInArea
```
public boolean executeInArea(BooleanSupplier 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:
    
    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.
    
    Parameters:
    
    logic - The runnable object whose run() method should be executed.
    
    Returns:
    
    the value return by the getAsBoolean() method.
  - visitNestedScopes
```
public void visitNestedScopes(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(Consumer), 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.
    Throws:
    
    StaticIllegalArgumentException - when visitor is null.
    
    ForEachTerminationException - when the traversal ends prematurely.
    
    Parameters:
    
    visitor - Determines the action to be performed on each of the children scopes.
    
    Since:
    
    RTSJ 2.0
  - finalize
```
protected final void finalize()
                       throws Throwable
```
    Synchronized helper for finalize to free the memory of this ScopedMemory.
    Since there is no specified way to release the memory of a memory area explicitly, this is done by this finalize method. However, since the execution time of the finalizer is not guaranteed by the system, and the memory may remain unreclaimed for too long, this method should be called explicitly by client code to make sure that the memory is reclaimed immediately when it is not needed any longer.
    
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    InternalError - when this is currently in use (i.e., it has a non-zero enter count.)
    
    Throwable - the Exception raised by this method
    
    See Also:
    
    WeakReference, PhantomReference

Class ScopedMemory

Method Summary

Methods inherited from class javax.realtime.MemoryArea

Methods inherited from class java.lang.Object

Method Detail

globalBackingStoreSize

globalBackingStoreConsumed

globalBackingStoreRemaining

visitScopeRoots

mayHoldReferenceTo

mayHoldReferenceTo

enter

enter

enter

enter

enter

enter

enter

getPortal

setPortal

getReferenceCount

getParent

toString

join

join

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

joinAndEnter

executeInArea

executeInArea

executeInArea

executeInArea

executeInArea

executeInArea

visitNestedScopes

finalize