javax.realtime
Class ScopedMemory

java.lang.Object
  |
  +--javax.realtime.MemoryArea
        |
        +--javax.realtime.ScopedMemory

Direct Known Subclasses:

CTMemory, LTMemory, LTPhysicalMemory, ScopedPhysicalMemory, VTMemory, VTPhysicalMemory

public abstract class ScopedMemory

extends MemoryArea

ScopedMemory is the abstract base class of all classes dealing with representations of memoryspaces 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.

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. Memory is allocated, as always, using an RTJ_malloc call.

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 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 objects in the memory are finalized and collected.

Objects allocated from a ScopedMemory area have a unique lifetime. They cease to exist on exiting 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 of heap objects may be stored into an object allocated in a ScopedMemory area.

Field Summary

private int	count
protected java.lang.Runnable	logic logic.run() is executed when enter() is called.
protected java.lang.Object	portal

Fields inherited from class javax.realtime.MemoryArea

constant, heap, id, memoryConsumed, nullClassArr, nullMem, nullObjArr, scoped, shadow, size

Constructor Summary

ScopedMemory(long size)
Create a new ScopedMemory with the given parameters.

ScopedMemory(long minimum, long maximum)

ScopedMemory(long size, java.lang.Runnable r)
Create a new ScopedMemory with the given parameters.

ScopedMemory(javax.realtime.SizeEstimator size)
Create a new ScopedMemory with the given parameters.

ScopedMemory(javax.realtime.SizeEstimator size, java.lang.Runnable r)
Create a new ScopedMemory with the given parameters.

Method Summary

void	checkAccess(java.lang.Object obj) Check to see if this ScopedMemory can have access to the given object.
void	checkNewInstance(javax.realtime.MemoryArea mem) Check to see if a newInstance can go through
void	enter() Associate this ScopedMemory area to the current realtime thread for the duration of the execution of the run() method of the current instance of Schedulable or the run() method of the instance of Schedulable fiven in the constructor.
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 current instance of Schedulable or the run() method of the instance of Schedulable fiven in the constructor.
long	getMaximumSize() Get the maximum size this memory area can attain.
javax.realtime.MemoryArea	getOuterScope() Get the MemoryArea which contains this ScopedMemory for the current RealtimeThread.
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(javax.realtime.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() and enter() such that no enter() from another thread can intervene between the two method invocations.
void	joinAndEnter(javax.realtime.HighResolutionTime time) Combine join() and enter() such that no enter() from another thread can intervene between the two method invocations.
void	joinAndEnter(java.lang.Runnable logic) Combine join() and enter() such that no enter() from another thread can intervene between the two method invocations.
void	joinAndEnter(java.lang.Runnable logic, javax.realtime.HighResolutionTime time) Combine join() and enter() 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.
protected void	setupMemBlock(javax.realtime.RealtimeThread rt) Cannot call this on a ScopedMemory (doesn't cleanup MemBlocks appropriately).
java.lang.String	toString() Returns a user-friendly representation of this ScopedMemory.

Methods inherited from class javax.realtime.MemoryArea

bless, enterMemBlock, executeInArea, exitMemBlock, getMemoryArea, initNative, memoryConsumed, memoryRemaining, newArray, newArray, newArray, newArray, newInstance, newInstance, newInstance, newInstance, postSetup, preSetup, registerFinal, shadow, size, startMem, stopMem, throwIllegalAssignmentError

Methods inherited from class java.lang.Object

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

Field Detail

portal

protected java.lang.Object portal

count

private int count

logic

protected java.lang.Runnable logic

logic.run() is executed when enter() is called.

Constructor Detail

ScopedMemory

public ScopedMemory(long size)

Create a new ScopedMemory with the given parameters.

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)

Create a new ScopedMemory with the given parameters.

Parameters:

size - The size of the new ScopedMemory area in bytes. If size is less than or equal to zero nothing happens.

r - The logic which will use the memory represented by this as its initial memory area.

ScopedMemory

public ScopedMemory(javax.realtime.SizeEstimator size)

Create a new ScopedMemory with the given parameters.

Parameters:

size - The size of the new ScopedMemory area estimated by an instance of SizeEstimator.

ScopedMemory

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

Create a new ScopedMemory with the given parameters.

Parameters:

size - The size of the new ScopedMemory area estimated by an instance of SizeEstimator.

r - The logic which will use the memory represented by this as its initial memory area.

ScopedMemory

public ScopedMemory(long minimum,
                    long maximum)

Method Detail

enter

public void enter()

Associate this ScopedMemory area to the current realtime thread for the duration of the execution of the run() method of the current instance of Schedulable or the run() method of the instance of Schedulable fiven in the constructor. 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

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 current instance of Schedulable or the run() method of the instance of Schedulable fiven in the constructor. 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.

Returns:

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

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

join

public void join(javax.realtime.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 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.

joinAndEnter

public void joinAndEnter()
                  throws java.lang.InterruptedException

Combine join() and 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 maethod returns immediately.

Throws:

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

joinAndEnter

public void joinAndEnter(javax.realtime.HighResolutionTime time)
                  throws java.lang.InterruptedException

Combine join() and 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 maethod returns immediately.

Parameters:

time - The time that bounds the wait.

Throws:

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

joinAndEnter

public void joinAndEnter(java.lang.Runnable logic)
                  throws java.lang.InterruptedException

Combine join() and 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 maethod returns immediately.

Parameters:

logic - The java.lang.Runnable object which contains the code to execute.

Throws:

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

joinAndEnter

public void joinAndEnter(java.lang.Runnable logic,
                         javax.realtime.HighResolutionTime time)
                  throws java.lang.InterruptedException

Combine join() and 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.

Parameters:

logic - The java.lang.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.

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.

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.

toString

public java.lang.String toString()

Returns a user-friendly representation of this ScopedMemory.

Overrides:

toString in class MemoryArea

Returns:

The string representation.

getOuterScope

public javax.realtime.MemoryArea getOuterScope()

Get the MemoryArea which contains this ScopedMemory for the current RealtimeThread.

Overrides:

getOuterScope in class MemoryArea

checkAccess

public void checkAccess(java.lang.Object obj)

Check to see if this ScopedMemory can have access to the given object.

Overrides:

checkAccess in class MemoryArea

checkNewInstance

public void checkNewInstance(javax.realtime.MemoryArea mem)

Check to see if a newInstance can go through

Overrides:

checkNewInstance in class MemoryArea

setupMemBlock

protected void setupMemBlock(javax.realtime.RealtimeThread rt)
                      throws java.lang.IllegalAccessException

Cannot call this on a ScopedMemory (doesn't cleanup MemBlocks appropriately). Should never need to, since that'll cause an access violation according to the spec.

java.lang.IllegalAccessException