javax.realtime
Class ScopedMemory

java.lang.Object
  javax.realtime.MemoryArea
      javax.realtime.ScopedMemory

Direct Known Subclasses:

CTMemory, LTMemory, PrivateScopedMemory, VTMemory

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 public void enter() throws ScopedCycleException 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 withthe 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 public void enter() throws ScopedCycleException 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 allo-cated in the Java heap.
• 2. A reference to an object in ScopedMemory can never be stored in an Object allo-cated in ImmortalMemor.
• 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.

Author:

Angelo Corsaro

Field Summary

protected char[]

joinSynchronizer

Fields inherited from class javax.realtime.MemoryArea

logic, parent, sizeInBytes

Constructor Summary

ScopedMemory(long size)
Creates a new ScopedMemory instance.

ScopedMemory(long size, Runnable logic)
Creates a new ScopedMemory instance.

ScopedMemory(SizeEstimator size)
Creates a new ScopedMemory instance.

ScopedMemory(SizeEstimator size, Runnable logic)
Creates a new ScopedMemory instance.

Method Summary

void	enter(Runnable logic) Associate this memory area to the current real-time 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.
Object	getPortal() Returns 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(Runnable logic) Combine join();enter(logic); such that no enter from another thread can intervene between the two method invocations.
void	joinAndEnter(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(Object portal) Set the argument to the portal object in the memory area represented by this instance of ScopedMemory.
String	toString() Returns a user-friendly representation of this ScopedMemory.

Methods inherited from class javax.realtime.MemoryArea

enter, executeInArea, finalize, fini, getMemoryArea, guardedRun, init, memoryConsumed, memoryRemaining, newArray, newInstance, newInstance, size

Methods inherited from class java.lang.Object

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

Field Detail

joinSynchronizer

protected char[] joinSynchronizer

Constructor Detail

ScopedMemory

public ScopedMemory(long size)

Creates a new ScopedMemory instance.

Parameters:

size - The size of MemoryArea to allocate, in bytes. If size is less than or equal to zero an IllegalArgumentException is thrown.

ScopedMemory

public ScopedMemory(long size,
                    Runnable logic)

Creates a new ScopedMemory instance.

Parameters:

size - The size of MemoryArea to allocate, in bytes. If size is less than or equal to zero an IllegalArgumentException is thrown.

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

ScopedMemory

public ScopedMemory(SizeEstimator size)

Creates a new ScopedMemory instance.

Parameters:

size - A SizeEstimator object which indicates the amount of memory required by this MemoryArea.

ScopedMemory

public ScopedMemory(SizeEstimator size,
                    Runnable logic)

Creates a new ScopedMemory instance.

Parameters:

size - The size of MemoryArea to allocate, in bytes.

logic - The run() method of this object will be called whenever enter() called.

Method Detail

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 Object getPortal()

Returns a reference to the portal object in this instance of ScopedMemory

Returns:

A reference to the portal or null if there is no portal set.

setPortal

public void setPortal(Object portal)

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 a ScopedMemory that is outer then the current.

Parameters:

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

join

public void join()
          throws InterruptedException

Wait until the reference count of this ScopedMemory goes down to zero.

Throws:

InterruptedException - If another thread interrupts this thread while it is waiting.

join

public void join(HighResolutionTime time)
          throws 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:

InterruptedException - if another thread interrupts this thread while it is waiting.

joinAndEnter

public void joinAndEnter()
                  throws 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:

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

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(Runnable logic)
                  throws 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:

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(Runnable logic,
                         HighResolutionTime time)
                  throws 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:

InterruptedException - if another thread interrupts this thread while it is waiting.

ScopedCycleException - If entering this ScopedMemory would violate the single parent rule.

toString

public String toString()

Returns a user-friendly representation of this ScopedMemory.

Returns:

The string representation

enter

public void enter(Runnable logic)
           throws ScopedCycleException

Associate this memory area to the current real-time 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 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

Parameters:

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

Throws:

ScopedCycleException - If entering this ScopedMemory would violate the single parent rule.