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

ScopedMemory(long size, java.lang.Runnable r)
Create a new ScopedMemory of size size and that executes r.run() when enter() is called.

ScopedMemory(SizeEstimator size)
Create a new ScopedMemory with size equal to size.getEstimate().

ScopedMemory(SizeEstimator size, java.lang.Runnable r)
Create a new ScopedMemory with size equal to size.getEstimate().

Method Summary

void	enter() Associate this ScopedMemory area to the current realtime thread for the duration of the execution of the run() method of the given Runnable.
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.
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, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ScopedMemory

public ScopedMemory(long size)

Create a new ScopedMemory of size size .

Parameters:

size - The size of the new ScopedMemory area in bytes. If size is less than or equal to zero an IllegalArgumentException is thrown.

ScopedMemory

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

Create a new ScopedMemory of size size and that executes r.run() when enter() is called.

Parameters:

size - The size of the new ScopedMemory area in bytes. If size is less than or equal to zero an IllegalArgumentException is thrown.

r - The Runnable whose run() method is invoked when any of the variations of enter() which do not take a Runnable is called.

ScopedMemory

public ScopedMemory(SizeEstimator size)

Create a new ScopedMemory with size equal to size.getEstimate().

Parameters:

size - A (@link SizeEstimator} which encapsulates the size of the new ScopedMemory area.

ScopedMemory

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

Create a new ScopedMemory with size equal to size.getEstimate(). and that executes r.run() when enter() is called.

Parameters:

size - A (@link SizeEstimator} which encapsulates the size of the new ScopedMemory area.

r - The Runnable whose run() method is invoked when any of the variations of enter() which do not take a Runnable is called.

Method Detail

enter

public void enter()
           throws ScopedCycleException

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.

enter

public void enter(java.lang.Runnable logic)
           throws ScopedCycleException

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 memory 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(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 construction 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.