javax.realtime
Class ScopedMemory

java.lang.Object
  |
  +--javax.realtime.MemoryArea
        |
        +--javax.realtime.ScopedMemory
Direct Known Subclasses:
LTMemory, LTPhysicalMemory, VTMemory, VTPhysicalMemory

public abstract class ScopedMemory
extends MemoryArea

ScopedMemory is the abstract base class of all classes dealing with representations of memory spaces with a limited lifetime. The ScopedMemory area is valid as long as there are real-time threads with access to it. A reference is created for each accessor when either a real-time thread is created with the ScopedMemory object as its memory area, or a real-time thread runs the enter() method for the memory area. When the last reference to the object is removed, by exiting the thread or exiting the enter() method, finalizers are run for all objects in the memory area, and the area is emptied.

A ScopedMemory area is a connection to a particular region of memory and reflects the current status of it. 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 scheme in use, but the memory space that object represents is not. Typically, the memory for a ScopedMemory area might be allocated using native method implementations that make appropriate use of malloc() and free() or similar routines to manipulate memory.

The enter() method of ScopedMemory is the mechanism used to activate a new memory scope. Entry into the scope is done by calling the method:

public void enter(Runnable r)

Where r is a Runnable object whose run() method represents the entry point to the code that will run in the new scope. Exit from the scope occurs when the r.run() completes. Allocations of objects within r.run() are done with the ScopedMemory area. When r.run() is complete, the scoped memory area is no longer active. Its reference count will be decremented and if it is zero all of the objects in the memory area finalized and collected.

Objects allocated from a ScopedMemory area have a unique lifetime. They cease to exist on exiting a enter() method or upon exiting the last real-time thread referencing the area, regardless of any references that may exist to the object. Thus, to maintain the safety of Java and avoid dangling references, a very restrictive set of rules apply to ScopedMemory area objects:

  1. A reference to an object in ScopedMemory can never be stored in an Object allocated in the Java heap.
  2. A reference to an object in ScopedMemory can never be stored in an Object allocated in ImmortalMemory.
  3. A reference to an object in ScopedMemory can only be stored in Objects allocated in the same ScopedMemory area, or into a -- more inner -- ScopedMemory area nested by the use of its enter() method.
  4. References to immortal or heap objects may be stored into an object allocated in a ScopedMemory area.


Constructor Summary
ScopedMemory(long size)
          Create a new ScopedMemory area with a particular size.
ScopedMemory(long size, java.lang.Runnable r)
           
ScopedMemory(SizeEstimator size)
           
ScopedMemory(SizeEstimator size, java.lang.Runnable r)
           
 
Method Summary
 void enter()
          Associate this memory area to the current real-time thread for the duration of the execution of the run() method of the java.lang.Runnable passed at constructin time.
 void enter(java.lang.Runnable logic)
          Associate this ScopedMemory area to the current realtime thread for the duration of the execution of the run() method of the given Runnable.
protected  void finalize()
           
 long getMaximumSize()
          Get the maximum size this memory area can attain.
 java.lang.Object getPortal()
          Return a reference to the portal object in this instance of ScopedMemory.
 int getReferenceCount()
          Returns the reference count of this ScopedMemory.
 void join()
          Wait until the reference count of this ScopedMemory goes down to zero.
 void join(HighResolutionTime time)
          Wait at most until the time designated by the time parameter for the reference count of this ScopedMemory to go down to zero.
 void joinAndEnter()
          Combine join();enter(); such that no enter from another thread can intervene between the two method invocations.
 void joinAndEnter(HighResolutionTime time)
          Combine join(time);enter(); such that no enter from another thread can intervene between the two method invocations.
 void joinAndEnter(java.lang.Runnable logic)
          Combine join();enter(logic); such that no enter from another thread can intervene between the two method invocations.
 void joinAndEnter(java.lang.Runnable logic, HighResolutionTime time)
          Combine join(time);enter(logic); such that no enter from another thread can intervene between the two method invocations.
 void setPortal(java.lang.Object object)
          Set the argument to the portal object in the memory area represented by this instance of ScopedMemory.
 java.lang.String toString()
          Returns a user-friendly representation of this ScopedMemory.
 
Methods inherited from class javax.realtime.MemoryArea
executeInArea, getMemoryArea, memoryConsumed, memoryRemaining, newArray, newInstance, newInstance, size
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ScopedMemory

public ScopedMemory(long size)
Create a new ScopedMemory area with a particular size.
Parameters:
size - The size of the new ScopedMemory area in bytes. If size is less than or equal to zero nothing happens.

ScopedMemory

public ScopedMemory(long size,
                    java.lang.Runnable r)

ScopedMemory

public ScopedMemory(SizeEstimator size)

ScopedMemory

public ScopedMemory(SizeEstimator size,
                    java.lang.Runnable r)
Method Detail

enter

public void enter()
Description copied from class: MemoryArea
Associate this memory area to the current real-time thread for the duration of the execution of the run() method of the java.lang.Runnable passed at constructin time. During this bound period of execution, all objects are allocated from the memory area until another one takes effect, or the enter() method is exited. A runtime exception is thrown if this method is called from thread other than a RealtimeThread or NoHeapRealtimeThread.
Overrides:
enter in class MemoryArea
Tags copied from class: MemoryArea
Throws:
java.lang.IllegalArgumentException - Thrown if no Runnable was passed in the constructor.
ScopedCycleException - If entering this ScopedMemory would violate the single parent rule.

enter

public void enter(java.lang.Runnable logic)
Associate this ScopedMemory area to the current realtime thread for the duration of the execution of the run() method of the given Runnable. During this bound period of execution, all objects are allocated from the ScopedMemory area until another one takes effect, or the enter() method is exited. A runtime exception is thrown if this method is called from a thread other than a RealtimeThread or NoHeapRealtimeThread.
Overrides:
enter in class MemoryArea
Parameters:
logic - The runnable object which contains the code to execute.

getMaximumSize

public long getMaximumSize()
Get the maximum size this memory area can attain. If this is a fixed size memorea area, the returned value will be equal to the initial size.
Returns:
The maximum size attainable.

getPortal

public java.lang.Object getPortal()
Return a reference to the portal object in this instance of ScopedMemory. For a more detailed explanation of portals see setPortal(java.lang.Object)
Returns:
The portal object or null if there is no portal object.

setPortal

public void setPortal(java.lang.Object object)
Set the argument to the portal object in the memory area represented by this instance of ScopedMemory.

A portal can serve as a means of interthread communication and they are used primarily when threads need to share an object that is allocated in a ScopedMemory. The portal object for a ScopedMemory must be allocated in the same ScopedMemory. Thus the following condition has to evaluate to true for the portal to be set

this.equals(MemoryArea.getMemoryArea(object))

Parameters:
object - The object which will become the portal for this. If null the previous portal object remains the portal object for this or if there was no previous portal object then there is still no portal object for this.

getReferenceCount

public int getReferenceCount()
Returns the reference count of this ScopedMemory. The reference count is an indication of the number of threads that may have access to this scope.
Returns:
The reference count of this ScopedMemory.

toString

public java.lang.String toString()
Returns a user-friendly representation of this ScopedMemory.
Overrides:
toString in class java.lang.Object
Returns:
The string representation

join

public void join(HighResolutionTime time)
          throws java.lang.InterruptedException
Wait at most until the time designated by the time parameter for the reference count of this ScopedMemory to go down to zero.
Parameters:
time - If this time is an absolute time, the wait is bounded by that point in time. If 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 - if another thread interrupts this thread while it is waiting.

join

public void join()
          throws java.lang.InterruptedException
Wait until the reference count of this ScopedMemory goes down to zero.
Throws:
java.lang.InterruptedException - If another thread interrupts this thread while it is waiting.

joinAndEnter

public void joinAndEnter()
                  throws java.lang.InterruptedException,
                         ScopedCycleException
Combine join();enter(); such that no enter from another thread can intervene between the two method invocations. The resulting method will wait for the reference count on this ScopedMemory to reach zero, then enter the ScopedMemory and execute the run method from logic passed in the constructor. If no Runnable was passed, the method returns immediately.
Throws:
java.lang.InterruptedException - If another thread interrupts this thread while it is waiting.
ScopedCycleException - If entering this ScopedMemory would violate the single parent rule.

joinAndEnter

public void joinAndEnter(HighResolutionTime time)
                  throws java.lang.InterruptedException,
                         ScopedCycleException
Combine join(time);enter(); such that no enter from another thread 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 at constructin time. If no Runnable was passed then this method returns immediately.
Parameters:
time - The time that bounds the wait.
Throws:
java.lang.InterruptedException - if another thread interrupts this thread while it is waiting.
ScopedCycleException - If entering this ScopedMemory would violate the single parent rule.

joinAndEnter

public void joinAndEnter(java.lang.Runnable logic)
                  throws java.lang.InterruptedException,
                         ScopedCycleException
Combine join();enter(logic); such that no enter from another thread 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
Parameters:
logic - The Runnable object which contains the code to execute.
Throws:
java.lang.InterruptedException - If another thread interrupts this thread while it is waiting.
ScopedCycleException - If entering this ScopedMemory would violate the single parent rule.

joinAndEnter

public void joinAndEnter(java.lang.Runnable logic,
                         HighResolutionTime time)
                  throws java.lang.InterruptedException,
                         ScopedCycleException
Combine join(time);enter(logic); such that no enter from another thread 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.
Parameters:
logic - The Runnable object which contains the code to execute.
time - The time that bounds the wait.
Throws:
java.lang.InterruptedException - if another thread interrupts this thread while it is waiting.
ScopedCycleException - If entering this ScopedMemory would violate the single parent rule.

finalize

protected void finalize()
                 throws java.lang.Throwable
Overrides:
finalize in class MemoryArea