|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.realtime.MemoryArea javax.realtime.ScopedMemory
public abstract class ScopedMemory
ScopedMemory
is the abstract base class of all classes dealing with
representations of memory spaces which have a limited lifetime. In general, objects
allocated in scoped memory are freed when (and only when) no schedulable object has
access to the objects in the scoped memory.
A ScopedMemory
area is a connection to a particular region of
memory and reflects the current status of that memory. 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 context, but the
memory space that object represents (it's backing store) is allocated from memory that is
not otherwise directly visible to Java code; e.g., it might be allocated with the C malloc
function. This backing store behaves effectively as if it were allocated when the associated scoped
memory object is constructed and freed at that scoped memory object's finalization.
The enter()
method of ScopedMemory
is one
mechanism used to make
a memory area the current allocation context.
The other mechanism for activating a memory area is making it
the initial memory area for a real-time thread or async event handler.
Entry into the scope is accomplished, for example, by calling the
method:
public void enter(Runnable logic)
where logic
is a instance of Runnable
whose run()
method represents
the entry point of the code that will run in the new scope. Exit
from the scope occurs between the time the runnable.run()
method completes and the time control
returns from the enter
method.
By default, allocations of objects within runnable.run()
are taken from
the backing store of the ScopedMemory
.
ScopedMemory
is an abstract class, but all specified methods include
implementations. The responsibilities of MemoryArea, ScopedMemory
and the classes that
extend ScopedMemory
are not specified. Application code should not extend ScopedMemory
without detailed knowledge of its implementation.
Constructor Summary | |
---|---|
ScopedMemory(long size)
Create a new ScopedMemory area with the given parameters. |
|
ScopedMemory(long size,
java.lang.Runnable logic)
Create a new ScopedMemory area with the given parameters. |
|
ScopedMemory(SizeEstimator size)
Create a new ScopedMemory area with the given parameters. |
|
ScopedMemory(SizeEstimator size,
java.lang.Runnable logic)
Create a new ScopedMemory area with the given parameters. |
Method Summary | |
---|---|
void |
enter()
Associate this memory area with the current schedulable object for the duration of the execution of the run() method of the
instance of Runnable given in the constructor. |
void |
enter(java.lang.Runnable logic)
Associate this memory area with the current schedulable object for the duration of the execution of the run()
method of the given Runnable. |
void |
executeInArea(java.lang.Runnable logic)
Execute the run method from the logic
parameter using this memory area as the current allocation
context. |
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 drop to zero. |
void |
joinAndEnter()
In the error-free case, joinAndEnter combines
join();enter(); such that no enter() from
another schedulable object can intervene between the two method invocations. |
void |
joinAndEnter(HighResolutionTime time)
In the error-free case, joinAndEnter combines
join();enter(); such that no enter() from
another schedulable object can intervene between the two method invocations. |
void |
joinAndEnter(java.lang.Runnable logic)
In the error-free case, joinAndEnter combines
join();enter(); such that no enter() from
another schedulable object can intervene between the two method invocations. |
void |
joinAndEnter(java.lang.Runnable logic,
HighResolutionTime time)
In the error-free case, joinAndEnter combines
join();enter(); such that no enter() from
another schedulable object can intervene between the two method invocations. |
java.lang.Object |
newArray(java.lang.Class type,
int number)
Allocate an array of the given type in this memory area. |
java.lang.Object |
newInstance(java.lang.Class type)
Allocate an object in this memory area. |
java.lang.Object |
newInstance(java.lang.reflect.Constructor c,
java.lang.Object[] args)
Allocate an object in this memory area. |
void |
setPortal(java.lang.Object object)
Sets the portal object of the memory area represented by this instance of ScopedMemory to the given object. |
java.lang.String |
toString()
Returns a user-friendly representation of this ScopedMemory of the
form Scoped memory # <num> where <num> is a number that uniquely
identifies this scoped memory area. |
Methods inherited from class javax.realtime.MemoryArea |
---|
getMemoryArea, memoryConsumed, memoryRemaining, size |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public ScopedMemory(long size)
ScopedMemory
area with the given parameters.
size
- The size of the new ScopedMemory
area
in bytes.
java.lang.IllegalArgumentException
- Thrown if size
is less than
zero.
java.lang.OutOfMemoryError
- Thrown if there is insufficient memory for the ScopedMemory
object or for the backing memory.public ScopedMemory(long size, java.lang.Runnable logic)
ScopedMemory
area with the given parameters.
size
- The size of the new ScopedMemory
area
in bytes.logic
- The Runnable
to execute when this
ScopedMemory
is entered. If logic
is null, this constructor is equivalent to constructing
the memory area without a logic value.
java.lang.IllegalArgumentException
- Thrown if size
is less than
zero.
IllegalAssignmentError
- Thrown if storing logic in this
would violate the assignment rules.
java.lang.OutOfMemoryError
- Thrown if there is insufficient memory for the ScopedMemory
object or for the backing memory.public ScopedMemory(SizeEstimator size)
ScopedMemory
area with the given parameters.
size
- The size of the new ScopedMemory
area
estimated by an instance of SizeEstimator
.
java.lang.IllegalArgumentException
- Thrown if size is null.
java.lang.OutOfMemoryError
- Thrown if there is insufficient memory for the ScopedMemory
object or for the backing memory.public ScopedMemory(SizeEstimator size, java.lang.Runnable logic)
ScopedMemory
area with the given parameters.
size
- The size of the new ScopedMemory
area
estimated by an instance of SizeEstimator
.logic
- The logic which will use the memory represented by this
as its initial memory area. If logic
is null, this constructor is equivalent to constructing
the memory area without a logic value.
java.lang.IllegalArgumentException
- Thrown if size is null.
java.lang.OutOfMemoryError
- Thrown if there is insufficient memory for the ScopedMemory
object or for the backing memory.
IllegalAssignmentError
- Thrown if storing logic in this would violate
the assignment rules.Method Detail |
---|
public void enter()
run()
method of the
instance of Runnable given in the constructor. During this
period of execution, this memory area becomes the default
allocation context until another default allocation context is
selected (using enter
, or executeInArea
(java.lang.Runnable))
or the enter method exits.
enter
in class MemoryArea
ScopedCycleException
- Thrown if this invocation would break the single
parent rule.
ThrowBoundaryError
- Thrown when the JVM needs to propagate an exception allocated in this
scope
to (or through) the memory area of the caller. Storing a reference to that exception would cause
an IllegalAssignmentError
, so the JVM cannot be permitted to deliver the exception.
The ThrowBoundaryError
is allocated in the current
allocation context and contains information about the exception it replaces.
java.lang.IllegalThreadStateException
- Thrown if the caller is a
Java thread.
java.lang.IllegalArgumentException
- Thrown no non-null value for logic
was supplied when the memory area was constructed.public void enter(java.lang.Runnable logic)
run()
method of the given Runnable. During this period of execution,
this memory area becomes the default allocation context until
another default allocation context is selected (using
enter
, or
executeInArea(java.lang.Runnable)
) or the
enter
method exits.
enter
in class MemoryArea
logic
- The Runnable object whose run()
method
should be invoked.
ScopedCycleException
- Thrown if this invocation would break the single
parent rule.
ThrowBoundaryError
- Thrown when the JVM needs to propagate an exception allocated in this
scope
to (or through) the memory area of the caller. Storing a reference to that exception would cause
an IllegalAssignmentError
, so the JVM cannot be permitted to deliver the exception.
The ThrowBoundaryError
is allocated in the current
allocation context and contains information about the exception it replaces.
java.lang.IllegalThreadStateException
- Thrown if the caller is a
Java thread.
java.lang.IllegalArgumentException
- Thrown if logic
is null.public void executeInArea(java.lang.Runnable logic)
run
method from the logic
parameter using this memory area as the current allocation
context. This method behaves as if it moves the allocation
context down the scope stack to the occurrence of
this
.
executeInArea
in class MemoryArea
logic
- The runnable object whose run()
method should
be executed.
java.lang.IllegalThreadStateException
- Thrown if the caller is a Java thread.
InaccessibleAreaException
- Thrown if the memory area is
not in the schedulable object's scope stack.public long getMaximumSize()
public java.lang.Object getPortal()
ScopedMemory
.
Assignment rules are enforced on the value returned by getPortal
as if the return value were first stored in an object allocated in the
current allocation context, then moved to
its final destination.
MemoryAccessError
- Thrown if the reference in the portal is a heap reference
and the caller is a no-heap schedulable object.
IllegalAssignmentError
- Thrown if a reference to the
portal object cannot be stored in the caller's allocation
context; that is, if this is "inner" relative to the current
allocation context.
java.lang.IllegalThreadStateException
- Thrown if the
caller is a Java thread.public int getReferenceCount()
ScopedMemory
.
The reference count is an indication of the number of schedulable objects
that may have access to this scope.
ScopedMemory
.public void join() throws java.lang.InterruptedException
ScopedMemory
goes down to zero.
Return immediately if the memory is unreferenced.
java.lang.InterruptedException
- If this schedulable object is interrupted by
RealtimeThread.interrupt()
or
AsynchronouslyInterruptedException.fire()
while waiting for the reference count to go to zero.public void join(HighResolutionTime time) throws java.lang.InterruptedException
time
parameter for
the reference count of this ScopedMemory
to drop to zero.
Return immediately if the memory area is unreferenced.
Since the time is expressed as a HighResolutionTime
, this
method is an accurate timer with nanosecond granularity. The
actual resolution of the timer and even the quantity it
measures depends on the clock associated with time. The delay
time may be relative or absolute. If relative, then the delay
is the amount of time given by time, and measured by its
associated clock. If absolute, then the delay is until the
indicated value is reached by the clock. If the given absolute
time is less than or equal to the current value of the clock,
the call to join returns immediately.
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.
java.lang.InterruptedException
- If this schedulable object is interrupted by
RealtimeThread.interrupt()
or
AsynchronouslyInterruptedException.fire()
while waiting for the reference count to go to zero.
java.lang.IllegalArgumentException
- Thrown if time
is null.
java.lang.UnsupportedOperationException
- Thrown if the
wait operation is not supported using the clock associated with
time.public void joinAndEnter() throws java.lang.InterruptedException
joinAndEnter
combines
join();enter();
such that no enter()
from
another schedulable object 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 instance of Runnable
was passed to the memory area's constructor,
the method throws IllegalArgumentException
immediately.
If multiple threads are waiting in joinAndEnter family methods for a memory area, at most one of them will be released each time the reference count goes to zero.
Note that although joinAndEnter guarantees that the reference count is zero when the schedulable object is released for entry, it does not guarantee that the reference count will remain one for any length of time. A subsequent enter could raise the reference count to two.
java.lang.InterruptedException
- If this schedulable object is interrupted by
RealtimeThread.interrupt()
or
AsynchronouslyInterruptedException.fire()
while waiting for the reference count to go to zero.
ThrowBoundaryError
- Thrown when the JVM needs to propagate an exception allocated in this
scope
to (or through) the memory area of the caller. Storing a reference to that exception would cause
an IllegalAssignmentError
, so the JVM cannot be permitted to deliver the exception.
The ThrowBoundaryError
is allocated in the current
allocation context and contains information about the exception it replaces.
java.lang.IllegalArgumentException
- Thrown if no non-null logic
value
was supplied to the memory area's constructor.public void joinAndEnter(HighResolutionTime time) throws java.lang.InterruptedException
joinAndEnter
combines
join();enter();
such that no enter()
from
another schedulable object 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 to the constructor. If no instance of Runnable
was passed to the memory area's constructor, the method
throws IllegalArgumentException
immediately.
If multiple threads are waiting in joinAndEnter family methods for a memory area, at most one of them will be released each time the reference count goes to zero.
Since the time is expressed as a HighResolutionTime, this method has an accurate timer with nanosecond granularity. The actual resolution of the timer and even the quantity it measures depends on the clock associated with time. The delay time may be relative or absolute. If relative, then the calling thread is blocked for at most the amount of time given by time, and measured by its associated clock. If absolute, then the time delay is until the indicated value is reached by the clock. If the given absolute time is less than or equal to the current value of the clock, the call to joinAndEnter returns immediately.
Note that although joinAndEnter guarantees that the reference count is zero when the schedulable object is released for entry, it does not guarantee that the reference count will remain one for any length of time. A subsequent enter could raise the reference count to two.
Note that expiration of time
may cause control to
enter the memory area before its reference count has gone to
zero.
time
- The time that bounds the wait.
ThrowBoundaryError
- Thrown when the JVM needs to propagate an exception allocated in this
scope
to (or through) the memory area of the caller. Storing a reference to that exception would cause
an IllegalAssignmentError
, so the JVM cannot be permitted to deliver the exception.
The ThrowBoundaryError
is allocated in the current
allocation context and contains information about the exception it replaces.
java.lang.InterruptedException
- If this schedulable object is interrupted by
RealtimeThread.interrupt()
or
AsynchronouslyInterruptedException.fire()
while waiting for the reference count to go to zero.
ScopedCycleException
- Thrown if this invocation would break the single
parent rule.
java.lang.IllegalArgumentException
- Thrown if time
is null, or if
no non-null logic
value
was supplied to the memory area's constructor.
java.lang.UnsupportedOperationException
- Thrown if the
wait operation is not supported using the clock associated with
time.public void joinAndEnter(java.lang.Runnable logic) throws java.lang.InterruptedException
joinAndEnter
combines
join();enter();
such that no enter()
from
another schedulable object 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
If logic
is null, throw IllegalArgumentException
immediately.
If multiple threads are waiting in joinAndEnter family methods for a memory area, at most one of them will be released each time the reference count goes to zero.
Note that although joinAndEnter guarantees that the reference count is zero when the schedulable object is released for entry, it does not guarantee that the reference count will remain one for any length of time. A subsequent enter could raise the reference count to two.
logic
- The Runnable
object which contains the code to execute.
java.lang.InterruptedException
- If this schedulable object is interrupted by
RealtimeThread.interrupt()
or
AsynchronouslyInterruptedException.fire()
while waiting for the reference count to go to zero.
ThrowBoundaryError
- Thrown when the JVM needs to propagate an exception allocated in this
scope
to (or through) the memory area of the caller. Storing a reference to that exception would cause
an IllegalAssignmentError
, so the JVM cannot be permitted to deliver the exception.
The ThrowBoundaryError
is allocated in the current
allocation context and contains information about the exception it replaces.
java.lang.IllegalArgumentException
- Thrown if logic
is null.public void joinAndEnter(java.lang.Runnable logic, HighResolutionTime time) throws java.lang.InterruptedException
joinAndEnter
combines
join();enter();
such that no enter()
from
another schedulable object 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
.
Since the time is expressed as a HighResolutionTime, this method is an accurate timer with nanosecond granularity. The actual resolution of the timer and even the quantity it measures depends on the clock associated with time. The delay time may be relative or absolute. If relative, then the delay is the amount of time given by time, and measured by its associated clock. If absolute, then the delay is until the indicated value is reached by the clock. If the given absolute time is less than or equal to the current value of the clock, the call to join returns immediately.
Throws IllegalArgumentException
immediately if logic
is null.
If multiple threads are waiting in joinAndEnter family methods for a memory area, at most one of them will be released each time the reference count goes to zero.
Note that although joinAndEnter guarantees that the reference count is zero when the schedulable object is released for entry, it does not guarantee that the reference count will remain one for any length of time. A subsequent enter could raise the reference count to two.
Note that expiration of time
may cause control to
enter the memory area before its reference count has gone to
zero.
logic
- The Runnable
object which contains the code to execute.time
- The time that bounds the wait.
java.lang.InterruptedException
- If this schedulable object is interrupted by
RealtimeThread.interrupt()
or
AsynchronouslyInterruptedException.fire()
while waiting for the reference count to go to zero.
ThrowBoundaryError
- Thrown when the JVM needs to propagate an exception allocated in this
scope
to (or through) the memory area of the caller. Storing a reference to that exception would cause
an IllegalAssignmentError
, so the JVM cannot be permitted to deliver the exception.
The ThrowBoundaryError
is allocated in the current
allocation context and contains information about the exception it replaces.
ScopedCycleException
- Thrown if this invocation would break the single
parent rule.
java.lang.IllegalArgumentException
- Thrown if time
or logic
is null.
java.lang.UnsupportedOperationException
- Thrown if the
wait operation is not supported using the clock associated with
time.public java.lang.Object newArray(java.lang.Class type, int number)
newArray
in class MemoryArea
type
- The class of the elements of the new array. To
create an array of a primitive type use a type such as
Integer.TYPE (which would call for an array of the primitive
int type.)number
- The number of elements in the new array.
java.lang.IllegalArgumentException
- Thrown if number
is less than zero, type
is
null, or type
is java.lang.Void.TYPE
.
java.lang.OutOfMemoryError
- Thrown if space in the memory area is exhausted.
java.lang.IllegalThreadStateException
- Thrown if the caller is a Java thread.
InaccessibleAreaException
- Thrown if the memory area is not in the schedulable object's
scope stack.public java.lang.Object newInstance(java.lang.Class type) throws java.lang.IllegalAccessException, java.lang.InstantiationException
newInstance
in class MemoryArea
type
- The class of which to create a new instance.
type
.
java.lang.IllegalAccessException
- The class or initializer is inaccessible.
java.lang.IllegalArgumentException
- Thrown if type
is
null.
java.lang.ExceptionInInitializerError
- Thrown if an unexpected exception has occurred in a static initializer
java.lang.OutOfMemoryError
- Thrown if space in the memory area is exhausted.
java.lang.InstantiationException
- Thrown if the specified class object could not be
instantiated. Possible causes are: it is an interface, it is abstract,
it is an array, or an exception was thrown by the constructor.
java.lang.IllegalThreadStateException
- Thrown if the caller is a Java thread.
InaccessibleAreaException
- Thrown if the memory area is not in the schedulable object's
scope stack.public java.lang.Object newInstance(java.lang.reflect.Constructor c, java.lang.Object[] args) throws java.lang.IllegalAccessException, java.lang.InstantiationException, java.lang.reflect.InvocationTargetException
newInstance
in class MemoryArea
c
- TThe constructor for the new instance.args
- An array of arguments to pass to the constructor.
c
.
java.lang.IllegalAccessException
- Thrown if the class or initializer is inaccessible under Java access control.
java.lang.InstantiationException
- Thrown if the specified class object could not be
instantiated. Possible causes are: it is an interface, it is abstract,
it is an array.
java.lang.OutOfMemoryError
- Thrown if space in the memory area is exhausted.
java.lang.IllegalArgumentException
- Thrown if c
is
null, or the args
array does not contain the number of arguments required by c
. A null
value of args
is treated like an array of length 0.
java.lang.IllegalThreadStateException
- Thrown if the caller is a Java thread.
java.lang.reflect.InvocationTargetException
- Thrown if
the underlying constructor throws an exception.
InaccessibleAreaException
- Thrown if the memory area is not in the schedulable object's
scope stack.public void setPortal(java.lang.Object object)
ScopedMemory
to the given object. The object must have been
allocated in this ScopedMemory
instance.
IllegalThreadStateException is thrown when called by a Java thread even when the invocation could also throw IllegalArgumentException.
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
.
IllegalAssignmentError
- Thrown if
object
is not allocated in this scoped memory instance.
InaccessibleAreaException
- Thrown if this memory area is
not in the caller's
scope stack.
java.lang.IllegalThreadStateException
- Thrown if the caller is a Java thread.public java.lang.String toString()
ScopedMemory
of the
form Scoped memory # <num>
where <num> is a number that uniquely
identifies this scoped memory area.
toString
in class java.lang.Object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |