|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.realtime.MemoryArea | +--javax.realtime.ScopedMemory
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:
ScopedMemory
can never be stored in an Object
allocated in the Java heap.ScopedMemory
can never be stored in an Object
allocated in ImmortalMemory
.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.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 |
public ScopedMemory(long size)
ScopedMemory
area with a particular size.size
- The size of the new ScopedMemory
area
in bytes. If size is less than or equal to zero
nothing happens.public ScopedMemory(long size, java.lang.Runnable r)
public ScopedMemory(SizeEstimator size)
public ScopedMemory(SizeEstimator size, java.lang.Runnable r)
Method Detail |
public void enter()
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
.Runnable
was passed in the constructor.public void enter(java.lang.Runnable logic)
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
.logic
- The runnable object which contains the code to execute.public long getMaximumSize()
public java.lang.Object getPortal()
ScopedMemory
. For a more detailed explanation of portals
see setPortal(java.lang.Object)
public void setPortal(java.lang.Object object)
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))
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.public int getReferenceCount()
ScopedMemory
.
The reference count is an indication of the number of threads
that may have access to this scope.ScopedMemory
.public java.lang.String toString()
ScopedMemory
.public void join(HighResolutionTime time) throws java.lang.InterruptedException
time
parameter for
the reference count of this ScopedMemory
to go down to zero.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.public void join() throws java.lang.InterruptedException
ScopedMemory
goes down to zero.public void joinAndEnter() throws java.lang.InterruptedException, ScopedCycleException
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.ScopedMemory
would
violate the single parent rule.public void joinAndEnter(HighResolutionTime time) throws java.lang.InterruptedException, ScopedCycleException
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.time
- The time that bounds the wait.ScopedMemory
would
violate the single parent rule.public void joinAndEnter(java.lang.Runnable logic) throws java.lang.InterruptedException, ScopedCycleException
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
logic
- The Runnable
object which contains the code to execute.ScopedMemory
would
violate the single parent rule.public void joinAndEnter(java.lang.Runnable logic, HighResolutionTime time) throws java.lang.InterruptedException, ScopedCycleException
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
.logic
- The Runnable
object which contains the code to execute.time
- The time that bounds the wait.ScopedMemory
would
violate the single parent rule.protected void finalize() throws java.lang.Throwable
|
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |