javax.realtime.memory

Class PinnableMemory

java.lang.Object

javax.realtime.MemoryArea

javax.realtime.memory.ScopedMemory

javax.realtime.memory.PinnableMemory

public class PinnableMemory
extends ScopedMemory

This class is for passing information between different threads as in the producer consumer pattern. One thread can enter an empty PinnableMemory, allocate some data structure, put a reference in the portal, pin the scope, exit it, and then pass it to another thread for further processing or consumption. Once the last thread is done, the memory can be unpinned, causing its contents to be freed.

Creation of a PinnableMemory shall fail with a StaticOutOfMemoryError when the current Schedulable has been configured with a ScopedMemoryParameters.getMaxGlobalBackingStore() that would be exceeded by said creation.

Since:

RTSJ 2.0

Constructor Summary

Constructors

Constructor and Description
PinnableMemory(long size) Creates a scoped memory of fixed size that can be held open when no Schedulable has it on its scoped memory stack.
PinnableMemory(long size, Runnable logic) Creates a scoped memory of fixed size that can be held open when no Schedulable has it on its scoped memory stack.
PinnableMemory(SizeEstimator size) Equivalent to PinnableMemory(long) with size.getEstimate() as its argument.
PinnableMemory(SizeEstimator size, Runnable logic) Equivalent to PinnableMemory(long, Runnable) with size.getEstimate() as its first argument.

Method Summary

Modifier and Type	Method and Description
int	getPinCount() Determine the current pin count.
boolean	isPinned() Determine the pin state of the memory.
void	joinAndEnterPinned() Same as ScopedMemory.joinAndEnter() except that the area may be pinned so the memory may not have been cleared.
void	joinAndEnterPinned(HighResolutionTime<?> limit) Same as ScopedMemory.joinAndEnter(HighResolutionTime) except that pinning is ignored so the memory may not have been cleared.
void	joinAndEnterPinned(Runnable logic) Same as ScopedMemory.joinAndEnter(Runnable) except that the area may be pinned so the memory may not have been cleared.
void	joinAndEnterPinned(Runnable logic, HighResolutionTime<?> limit) Same as ScopedMemory.joinAndEnter(Runnable, HighResolutionTime) except that pinning is ignored so the memory may not have been cleared.
void	joinPinned() Same as ScopedMemory.join() except that the area may be pinned so the memory may not have been cleared.
void	joinPinned(HighResolutionTime<?> limit) Same as ScopedMemory.join(HighResolutionTime) except that the area may be pinned so the memory may not have been cleared.
void	pin() Prevents the contents from being freed.
void	unpin() Allows the contents to be freed once no Schedulable is active within the scope.

Methods inherited from class javax.realtime.memory.ScopedMemory

enter, enter, executeInArea, getPortal, getReferenceCount, join, join, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, mayHoldReferenceTo, mayHoldReferenceTo, setPortal, toString

Methods inherited from class javax.realtime.MemoryArea

enter, enter, enter, enter, enter, executeInArea, executeInArea, executeInArea, executeInArea, executeInArea, getMemoryArea, memoryConsumed, memoryRemaining, newArray, newArrayInArea, newInstance, newInstance, size

Methods inherited from class java.lang.Object

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

Constructor Detail

PinnableMemory

public PinnableMemory(long size)

Creates a scoped memory of fixed size that can be held open when no Schedulable has it on its scoped memory stack.

Throws:

StaticIllegalArgumentException - when size is less than zero.

StaticOutOfMemoryError - when there is insufficient memory for the PinnalbeMemory object or for its allocation area in its backing store, or when the current Schedulable would exceed its configured allowance of global backing store.

Parameters:

size - The number of bytes in the memory area.

PinnableMemory

public PinnableMemory(long size,
                      Runnable logic)

Creates a scoped memory of fixed size that can be held open when no Schedulable has it on its scoped memory stack.

Throws:

StaticIllegalArgumentException - when size is less than zero.

StaticOutOfMemoryError - when there is insufficient memory for the PinnalbeMemory object or for its allocation area in its backing store, or when the current Schedulable would exceed its configured allowance of global backing store.

Parameters:

size - The number of bytes in the memory area.

logic - The logic to execute when none is provide at enter.

PinnableMemory

public PinnableMemory(SizeEstimator size)

Equivalent to PinnableMemory(long) with size.getEstimate() as its argument.

Throws:

StaticIllegalArgumentException - when size is null.

StaticOutOfMemoryError - when there is insufficient memory for the PinnalbeMemory object or for its allocation area in its backing store, or when the current Schedulable would exceed its configured allowance of global backing store.

Parameters:

size - An estimator for determining the number of bytes in the memory area.

PinnableMemory

public PinnableMemory(SizeEstimator size,
                      Runnable logic)

Equivalent to PinnableMemory(long, Runnable) with size.getEstimate() as its first argument.

Throws:

StaticIllegalArgumentException - when size is null.

StaticOutOfMemoryError - when there is insufficient memory for the PinnalbeMemory object or for its allocation area in its backing store, or when the current Schedulable would exceed its configured allowance of global backing store.

Parameters:

size - An estimator for determining the number of bytes in the memory area.

logic - The logic to execute when none is provide at enter.

Method Detail

pin

public void pin()

Prevents the contents from being freed.

Throws:

StaticIllegalStateException - when the current allocation context is not this allocation context.

unpin

public void unpin()

Allows the contents to be freed once no Schedulable is active within the scope. The unpin method must be called as many times as pin() to take effect. If there is no task in the area when the call takes affect, then the object in the area are reclaimed immediately, in the caller's context.

Throws:

StaticIllegalStateException - when the current allocation context is not this allocation context.

isPinned

public boolean isPinned()

Determine the pin state of the memory.

Returns:

true when the area is still pinned and false otherwise.

getPinCount

public int getPinCount()

Determine the current pin count.

Returns:

the number of times pin() has been called more than unpin().

joinPinned

public void joinPinned(HighResolutionTime<?> limit)
                throws InterruptedException

Same as ScopedMemory.join(HighResolutionTime) except that the area may be pinned so the memory may not have been cleared.

Throws:

InterruptedException - when this schedulable is interrupted by RealtimeThread.interrupt() or javax.realtime.control.AsynchronouslyInterruptedException#fire() while waiting for the reference count to go to zero.

Parameters:

limit - The maximum time to wait.

joinPinned

public void joinPinned()
                throws InterruptedException

Same as ScopedMemory.join() except that the area may be pinned so the memory may not have been cleared.

Throws:

InterruptedException - when this schedulable is interrupted by RealtimeThread.interrupt() or javax.realtime.control.AsynchronouslyInterruptedException#fire() while waiting for the reference count to go to zero.

joinAndEnterPinned

public void joinAndEnterPinned()
                        throws InterruptedException,
                               ScopedCycleException,
                               IllegalTaskStateException,
                               MemoryAccessError

Same as ScopedMemory.joinAndEnter() except that the area may be pinned so the memory may not have been cleared.

Throws:

ScopedCycleException - when the caller is a schedulable and this invocation would break the single parent rule.

InterruptedException - when this schedulable is interrupted by RealtimeThread.interrupt() or javax.realtime.control.AsynchronouslyInterruptedException#fire() while waiting for the reference count to go to zero.

IllegalTaskStateException - when the caller is a Java thread, or when this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the instance of Schedulable that triggered finalization. This would include the scope containing the instance of Schedulable, and the scope (if any) containing the scope containing the instance of Schedulable.

MemoryAccessError - when calling schedulable may not use the heap and this memory area's logic value is allocated in heap memory.

joinAndEnterPinned

public void joinAndEnterPinned(Runnable logic)
                        throws InterruptedException,
                               ScopedCycleException,
                               StaticIllegalArgumentException,
                               IllegalTaskStateException,
                               MemoryAccessError

Same as ScopedMemory.joinAndEnter(Runnable) except that the area may be pinned so the memory may not have been cleared.

Throws:

ScopedCycleException - when the caller is a schedulable and this invocation would break the single parent rule.

StaticIllegalArgumentException - when logic is null.

InterruptedException - when this schedulable is interrupted by RealtimeThread.interrupt() or javax.realtime.control.AsynchronouslyInterruptedException#fire() while waiting for the reference count to go to zero.

IllegalTaskStateException - when the caller is a Java thread, or when this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the instance of Schedulable that triggered finalization. This would include the scope containing the instance of Schedulable, and the scope (if any) containing the scope containing the instance of Schedulable.

MemoryAccessError - when calling schedulable may not use the heap and this memory area's logic value is allocated in heap memory.

Parameters:

logic - the code to be executed in this memory area.

joinAndEnterPinned

public void joinAndEnterPinned(HighResolutionTime<?> limit)
                        throws InterruptedException,
                               ScopedCycleException,
                               StaticIllegalArgumentException,
                               IllegalTaskStateException,
                               MemoryAccessError,
                               StaticUnsupportedOperationException

Same as ScopedMemory.joinAndEnter(HighResolutionTime) except that pinning is ignored so the memory may not have been cleared.

Throws:

ScopedCycleException - when the caller is a schedulable and this invocation would break the single parent rule.

InterruptedException - when this schedulable is interrupted by RealtimeThread.interrupt() or javax.realtime.control.AsynchronouslyInterruptedException#fire() while waiting for the reference count to go to zero.

IllegalTaskStateException - when the caller is a Java thread, or when this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the SO that triggered finalization. This would include the scope containing the SO, and the scope (if any) containing the scope containing the SO.

StaticIllegalArgumentException - when the caller is a schedulable, and limit is null or no non-null logic value was supplied to the memory area's constructor.

MemoryAccessError - when calling schedulable may not use the heap and this memory area's logic value is allocated in heap memory.

StaticUnsupportedOperationException - when the wait operation is not supported using the clock associated with limit.

Parameters:

limit - The maximum time to wait.

joinAndEnterPinned

public void joinAndEnterPinned(Runnable logic,
                               HighResolutionTime<?> limit)
                        throws InterruptedException,
                               IllegalTaskStateException,
                               StaticIllegalArgumentException,
                               StaticUnsupportedOperationException,
                               ScopedCycleException,
                               MemoryAccessError

Same as ScopedMemory.joinAndEnter(Runnable, HighResolutionTime) except that pinning is ignored so the memory may not have been cleared.

Throws:

InterruptedException - when this schedulable is interrupted by RealtimeThread.interrupt() or javax.realtime.control.AsynchronouslyInterruptedException#fire() while waiting for the reference count to go to zero.

ScopedCycleException - when the caller is a schedulable and this invocation would break the single parent rule.

IllegalTaskStateException - when the caller is a Java thread, or when this method is invoked during finalization of objects in scoped memory and entering this scoped memory area would force deletion of the instance of Schedulable that triggered finalization. This would include the scope containing the instance of Schedulable, and the scope (if any) containing the scope containing the instance of Schedulable.

StaticIllegalArgumentException - when the caller is a schedulable, and limit is null or no non-null logic value was supplied to the memory area's constructor.

MemoryAccessError - when calling schedulable may not use the heap and this memory area's logic value is allocated in heap memory.

StaticUnsupportedOperationException - when the wait operation is not supported using the clock associated with limit.

Parameters:

logic - The logic to execute upon entry.

limit - The maximum time to wait.