javax.realtime.memory

Class StackedMemory

java.lang.Object

javax.realtime.MemoryArea

javax.realtime.memory.ScopedMemory

javax.realtime.memory.StackedMemory

public class StackedMemory
extends ScopedMemory

StackedMemory implements a scoped memory allocation area and backing store management system. It is designed to allow for safe, fragmentation-free management of scoped allocation with certain strong guarantees provided by the virtual machine and runtime libraries.

Each StackedMemory instance represents a single object allocation area and additional memory associated with it in the form of a backing store. The backing store associated with a StackedMemory is a fixed-size memory area allocated at or before instantiation of the StackedMemory. The object allocation area is taken from the associated backing store, and the backing store may be further subdivided into additional StackedMemory allocation areas or backing stores by instantiating additional StackedMemory objects.

When a StackedMemory is created with a backing store, the backing store may be taken from a notional global backing store, in which case it is effectively immortal, or it may be taken from the enclosing StackedMemory's backing store when the scope in which it is created is also a StackedMemory. In this case it is returned to its enclosing scope's backing store when the object is finalized. Implementations should return the space occupied by backing stores taken from the global backing store when their associated StackedMemory object is finalized.

These backing store semantics divide instances of StackedMemory into two categories:

• host — this denotes a StackedMemory with an object allocation area created in a new backing store, allocated either from the global store or from a parent StackedMemory's backing store, and
• guest — this in turn indicates a StackedMemory with an object allocation area taken directly from a parent StackedMemory's backing store without creating a sub-store.

In addition, there is one distinguished status for StackedMemory object: root. A root StackedMemory is a host StackedMemory created with a backing store drawn directly from the global backing store, created in an allocation context of some type other than StackedMemory.

Creation of a StackedMemory shall fail with a StaticOutOfMemoryError when the current Schedulable is configured with a limit on ScopeParameters.maxGlobalBackingStore and creation of the root StackedMemory would exceed that limit.

Creation of a StackedMemory is subject to additional restrictions when the current Schedulable is configured with an explicit initial memory area of type StackedMemory. In this case, the following rules apply.

• Construction of a root StackedMemory will fail and throw a StaticOutOfMemoryError regardless of the value of the Schedulable's ScopeParameters.maxGlobalBackingStore.
• Construction of a StackedMemory from a current allocation context that is not the Schedulable's explicit initial memory area or one of its descendants in the scope stack will fail and throw StaticOutOfMemoryError.
• A maximum of ScopeParameters.maxInitialBackingStore bytes may be allocated directly from the backing store of the Schedulable's explicit initial memory area over the lifetime of the Schedulable. Any operation that would exceed this limit (whether by resizing the allocation area of the explicit initial memory area or a guest area in the same backing store, or by allocating a new StackedMemory with the explicit initial memory area as the current allocation context) will fail and throw a StaticOutOfMemoryError.

Allocations from a StackedMemory object allocation area are guaranteed to run in time linear in the size of the allocation. All memory for the backing store must be reserved at object construction time.

StackedMemory memory areas have two additional stacking constraints in addition to the single parent rule, designed to enable fragmentation-free manipulation:

• a StackedMemory that is created when another StackedMemory is the current allocation context can only be entered from the same allocation context in which it was created, and
• a guest StackedMemory cannot be created from a StackedMemory that currently has another child area that is also a guest StackedMemory, i.e., a StackedMemory can have at most one direct child that is a guest StackedMemory.

The StackedMemory constructor semantics also enforce the property that a StackedMemory cannot be created from another StackedMemory allocation context unless it is allocated from that context's backing store as either a host or guest area.

The backing store of a StackedMemory behaves as if any StackedMemory object allocation areas are at the “bottom” of the backing store, while the backing stores for enclosed StackedMemory areas are taken from the “top” of the backing store.

There may be an implementation-specific memory overhead for creating a backing store of a given size. This means that creating a StackedMemory with a backing store of exactly the remaining available backing store of the current StackedMemory may fail with an javax.realtime.StaticOutOfMemoryError. This overhead must be bounded by a constant.

Since:

RTSJ 2.0

Constructor Summary

Constructors

Constructor and Description
StackedMemory(long scopeSize) Equivalent to StackedMemory(long, Runnable) with argument list (scopeSize, null).
StackedMemory(long scopeSize, long backingSize) Equivalent to StackedMemory(long, long, Runnable) with argument list (scopeSize, backingSize, null).
StackedMemory(long scopeSize, long backingSize, java.lang.Runnable logic) Creates a host StackedMemory with an object allocation area and backing store of the specified sizes, bound to the specified Runnable.
StackedMemory(long scopeSize, java.lang.Runnable logic) Create a guest StackedMemory with an object allocation area of the specified size, bound to the specified Runnable.
StackedMemory(SizeEstimator scopeSize) Equivalent to StackedMemory(long, Runnable) with argument list (scopeSize.getEstimate(), null).
StackedMemory(SizeEstimator scopeSize, java.lang.Runnable logic) Equivalent to StackedMemory(long, Runnable) with argument list (scopeSize.getEstimate(), runnable).
StackedMemory(SizeEstimator scopeSize, SizeEstimator backingSize) Equivalent to StackedMemory(long, long, Runnable) with argument list (scopeSize.getEstimate(), backingSize.getEstimate(), null).
StackedMemory(SizeEstimator scopeSize, SizeEstimator backingSize, java.lang.Runnable logic) Equivalent to StackedMemory(long, long, Runnable) with argument list (scopeSize.getEstimate(), backingSize.getEstimate(), runnable).

Method Summary

Modifier and Type	Method and Description
void	enter() Associates this memory area with the current Schedulable object for the duration of the run() method of the instance of Runnable given in this object's constructor.
void	enter(java.lang.Runnable logic) Associates this memory area with the current Schedulable object for the duration of the run() method of the given Runnable.
long	getMaximumSize() Gets the maximum size this memory area can attain.
long	hostBackingStoreConsumed() Return the backing store consumed in bytes
long	hostBackingStoreRemaining() Return the backing store consumed in bytes
long	hostBackingStoreSize() Return the backing store consumed in bytes
void	resize(long scopeSize) Changes the size of the object allocation area for this scope.
java.lang.String	toString() Returns a user-friendly representation of this ScopedMemory of the form <class-name>@<num>" where <class-name> is the name of the class, e.g.

Methods inherited from class javax.realtime.memory.ScopedMemory

enter, enter, enter, enter, enter, executeInArea, executeInArea, executeInArea, executeInArea, executeInArea, executeInArea, finalize, getParent, getPortal, getReferenceCount, globalBackingStoreConsumed, globalBackingStoreRemaining, globalBackingStoreSize, join, join, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnterInternal, joinAndEnterInternal, joinAndEnterInternal, joinAndEnterInternal, joinAndEnterInternal, mayHoldReferenceTo, mayHoldReferenceTo, setPortal, visitNestedScopes, visitScopeRoots

Methods inherited from class javax.realtime.MemoryArea

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

Methods inherited from class java.lang.Object

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

Constructor Detail

StackedMemory

public StackedMemory(long scopeSize,
                     long backingSize)

Equivalent to StackedMemory(long, long, Runnable) with argument list (scopeSize, backingSize, null).

Parameters:

scopeSize - Size of the allocation area within the backing store.

backingSize - Size of the total backing store.

Throws:

java.lang.IllegalArgumentException - when either scopeSize or backingSize is less than zero, or when scopeSize is too large to be allocated from a backing store of size backingSize.

StaticOutOfMemoryError - when there is insufficient memory available to reserve the requested backing store, or when the current Schedulable has a StackedMemory as its explicit initial scoped memory area and that area is not on the scope stack.

StackedMemory

public StackedMemory(long scopeSize,
                     long backingSize,
                     java.lang.Runnable logic)

Creates a host StackedMemory with an object allocation area and backing store of the specified sizes, bound to the specified Runnable. The backing store is allocated from the currently active memory area when it is also a StackedMemory, and the global backing store otherwise. The object allocation area is allocated from the backing store.

Parameters:

scopeSize - Size of the allocation area within the backing store.

backingSize - Size of the total backing store.

logic - Runnable to be entered using this as its current memory area when enter() is called.

Throws:

java.lang.IllegalArgumentException - when either scopeSize or backingSize is less than zero, or when scopeSize is too large to be allocated from a backing store of size backingSize.

StaticOutOfMemoryError - when there is insufficient memory available to reserve the requested backing store, or when the current Schedulable has a StackedMemory as its explicit initial scoped memory area and that area is not on the scope stack.

StackedMemory

public StackedMemory(SizeEstimator scopeSize,
                     SizeEstimator backingSize)

Equivalent to StackedMemory(long, long, Runnable) with argument list (scopeSize.getEstimate(), backingSize.getEstimate(), null).

Parameters:

scopeSize - SizeEstimator indicating the size of the object allocation area within the backing store.

backingSize - SizeEstimator indicating the size of the total backing store.

Throws:

java.lang.IllegalArgumentException - when either scopeSize or backingSize is null, or when scopeSize.getEstimate() is too large to be allocated from a backing store of size. backingSize.getEstimate().

StaticOutOfMemoryError - when there is insufficient memory available to reserve the requested backing store, or when the current Schedulable has a StackedMemory as its explicit initial scoped memory area and that area is not on the scope stack.

StackedMemory

public StackedMemory(SizeEstimator scopeSize,
                     SizeEstimator backingSize,
                     java.lang.Runnable logic)

Equivalent to StackedMemory(long, long, Runnable) with argument list (scopeSize.getEstimate(), backingSize.getEstimate(), runnable).

Parameters:

scopeSize - SizeEstimator indicating the size of the object allocation area within the backing store.

backingSize - SizeEstimator indicating the size of the total backing store.

logic - Runnable to be entered using this as its current memory area when enter() is called.

Throws:

java.lang.IllegalArgumentException - when either scopeSize or backingSize is null, or when scopeSize.getEstimate() is too large to be allocated from a backing store of size backingSize.getEstimate().

StaticOutOfMemoryError - when there is insufficient memory available to reserve the requested backing store, or when the current Schedulable has a StackedMemory as its explicit initial scoped memory area and that area is not on the scope stack.

StackedMemory

public StackedMemory(long scopeSize)

Equivalent to StackedMemory(long, Runnable) with argument list (scopeSize, null).

Parameters:

scopeSize - Size of the allocation area within the backing store.

Throws:

java.lang.IllegalStateException - when the parent memory area is not a StackedMemory, or when the parent StackedMemory already has a child that is also a guest StackedMemory.

java.lang.IllegalArgumentException - when scopeSize is less than zero.

StaticOutOfMemoryError - when there is insufficient memory available in the backing store of the parent StackedMemory's object allocation area to reserve the requested object allocation area, or when the current Schedulable has a StackedMemory as its explicit initial scoped memory area and that area is not on the scope stack.

StackedMemory

public StackedMemory(SizeEstimator scopeSize)

Equivalent to StackedMemory(long, Runnable) with argument list (scopeSize.getEstimate(), null).

Parameters:

scopeSize - SizeEstimator indicating the size of the object allocation area within the backing store.

Throws:

java.lang.IllegalStateException - when the parent memory area is not a StackedMemory, or when the parent StackedMemory already has a child that is also a guest StackedMemory.

java.lang.IllegalArgumentException - when scopeSize is null.

StaticOutOfMemoryError - when there is insufficient memory available in the backing store of the parent StackedMemory's object allocation area to reserve the requested object allocation area, or when the current Schedulable has a StackedMemory as its explicit initial scoped memory area and that area is not on the scope stack.

StackedMemory

public StackedMemory(long scopeSize,
                     java.lang.Runnable logic)

Create a guest StackedMemory with an object allocation area of the specified size, bound to the specified Runnable. The object allocation area is drawn from the same backing store as the parent scope's object allocation area. The parent scope must be a StackedMemory.

Parameters:

scopeSize - Size of the allocation area within the backing store.

logic - Runnable to be entered using this as its current memory area when enter() is called.

Throws:

java.lang.IllegalStateException - when the parent memory area is not a StackedMemory, or when the parent StackedMemory already has a child that is also a guest StackedMemory.

java.lang.IllegalArgumentException - when scopeSize is less than zero.

StaticOutOfMemoryError - when there is insufficient memory available in the backing store of the parent StackedMemory's object allocation area to reserve the requested object allocation area.

StackedMemory

public StackedMemory(SizeEstimator scopeSize,
                     java.lang.Runnable logic)

Equivalent to StackedMemory(long, Runnable) with argument list (scopeSize.getEstimate(), runnable).

Parameters:

scopeSize - SizeEstimator indicating the size of the object allocation area within the backing store.

logic - Runnable to be entered using this as its current memory area when enter() is called.

Throws:

java.lang.IllegalStateException - when the parent memory area is not a StackedMemory, or when the parent StackedMemory already has a child that is also a guest StackedMemory.

java.lang.IllegalArgumentException - when scopeSize is null.

StaticOutOfMemoryError - when there is insufficient memory available in the backing store of the parent StackedMemory's object allocation area to reserve the requested object allocation area, or when the current Schedulable has a StackedMemory as its explicit initial scoped memory area and that area is not on the scope stack.

Method Detail

enter

public void enter()

Associates this memory area with the current Schedulable object for the duration of the run() method of the instance of Runnable given in this object's constructor. During this period of execution, this memory area becomes the default allocation context until another default allocation context is selected.

This method may only be called from the memory area in which this scope was created.

Overrides:

enter in class ScopedMemory

Throws:

java.lang.IllegalStateException - when the currently active memory area is a StackedMemory and is not the area in which this scope was created, or the current memory area is not a StackedMemory and this StackedMemory is not a root area.

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 may not be permitted to deliver the exception. The ThrowBoundaryError is allocated in the current allocation context and contains information about the exception it replaces.

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

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

java.lang.IllegalStateException

See Also:

ScopedMemory.enter()

enter

public void enter(java.lang.Runnable logic)

Associates this memory area with the current Schedulable object for the duration of the 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.

This method may only be called from the memory area in which this scope was created.

Overrides:

enter in class ScopedMemory

Parameters:

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

Throws:

java.lang.IllegalStateException - when the currently active memory area is a StackedMemory and is not the area in which this scope was created, or the current memory area is not a StackedMemory and this StackedMemory is not a root area.

ThrowBoundaryError - 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 may not be permitted to deliver the exception. The ThrowBoundaryError is allocated in the current allocation context and contains information about the exception it replaces.

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

MemoryAccessError

java.lang.IllegalStateException

See Also:

ScopedMemory.enter(Runnable)

resize

public void resize(long scopeSize)

Changes the size of the object allocation area for this scope. This method may be used to either grow or shrink the allocation area when there are no objects allocated in the scope and no Schedulable object has this area as its current allocation context. It may be used to grow the allocation area, or to shrink the allocation area no smaller than the size of its current usage, when the calling Schedulable object is the only object that has this area on its scope stack and there are no guest StackedMemory object allocation areas created after this area in the same backing store but not yet finalized.

Parameters:

scopeSize - The new allocation area size for this scope.

Throws:

java.lang.IllegalStateException - when the caller is not permitted to perform the requested adjustment or there are additional guest StackedMemory allocation areas after this one in the backing store.

StaticOutOfMemoryError - when the remaining backing store is insufficient for the requested adjustment, or when the current Schedulable has a StackedMemory as its explicit initial scoped memory area and that area is not on the scope stack.

getMaximumSize

public long getMaximumSize()

Gets the maximum size this memory area can attain. The value returned by this function is the maximum size that can currently be passed to resize(long) without triggering an OutOfMemoryException.

Returns:

the maximum size attainable.

hostBackingStoreSize

public long hostBackingStoreSize()

Return the backing store consumed in bytes

Returns:

the memory consumed in bytes

hostBackingStoreRemaining

public long hostBackingStoreRemaining()

Return the backing store consumed in bytes

Returns:

the memory consumed in bytes

hostBackingStoreConsumed

public long hostBackingStoreConsumed()

Return the backing store consumed in bytes

Returns:

the memory consumed in bytes

toString

public java.lang.String toString()

Description copied from class: ScopedMemory

Returns a user-friendly representation of this ScopedMemory of the form <class-name>@<num>" where <class-name> is the name of the class, e.g. javax.realtime.memory.ScopedMemory, and <num> is a number that uniquely identifies this scoped memory area.

Overrides:

toString in class ScopedMemory

Returns:

the string representation