javax.realtime
Class StackedMemory

java.lang.Object
  javax.realtime.MemoryArea
      javax.realtime.ScopedMemory
          javax.realtime.StackedMemory

public class StackedMemory
extends ScopedMemory

StackedMemory implements a scoped memory allocation area and container 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 in the form of a backing memory and additional memory associated with it in the form of a container. The container associated with a StackedMemory is a fixed-size memory area allocated at or before instantiation of the StackedMemory. The backing memory is taken from the associated container, and the container may be further subdivided into additional StackedMemory backing memories or containers by instantiating additional StackedMemory objects.

If a StackedMemory is created with a container, the container may be taken from a notional global container, in which case it is immortal, or it may be taken from the enclosing StackedMemory's container if the scope in which it is created is also a StackedMemory, in which case it is released when the object is finalized. Implementations are not required to release containers taken from the global container even if their associated StackedMemory object is finalized.

These container semantics divide instances of ScopedMemory into two categories:

• Host — this denotes a StackedMemory with a backing memory created in a new container, allocated either from the global container or from a parent StackedMemory's container.
• Guest — this in turn indicates a ScopedMemory with a backing memory taken directly from a parent StackedMemory's container store without creating a sub-container.

In addition, there is one distinguished status for StackedMemory objects, root. A root StackedMemory is a host StackedMemory created with a container drawn directly from the global backing store and having a parent memory area of some type other than StackedMemory.

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

StackedMemory memory areas have several 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.
• A guest StackedMemory cannot be created from a StackedMemory that currently has another child area that is also a guest StackedMemory. (That is, a StackedMemory can have at most one direct child that is a guest StackedMemory.)
• A StackedMemory cannot be created from another StackedMemory allocation context unless it is allocated from that context's container as either a host or guest area.

The container of a StackedMemory behaves as if any StackedMemory backing memories are at the “bottom” of the container, while the containers for enclosed StackedMemory areas are taken from the “top” of the container.

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

Since:

RTSJ 2.0

Field Summary

Fields inherited from class javax.realtime.MemoryArea

memoryAreaHeapLock

Constructor Summary

StackedMemory(long backingMemorySize)
Create a guest StackedMemory with a backing memory of the specified size.

StackedMemory(long backingMemorySize, long containerSize)
Create a host StackedMemory with a backing memory in a container of the specified sizes.

StackedMemory(long backingMemorySize, long containerSize, Runnable logic)
Create a host StackedMemory with a backing memory in a container of the specified sizes, bound to the specified Runnable..

StackedMemory(long backingMemorySize, Runnable logic)
Create a guest StackedMemory with an object allocation area of the specified size, bound to the specified Runnable.

StackedMemory(SizeEstimator backingMemorySize)
Create a guest StackedMemory with a backing memory of the size estimated by the specified SizeEstimator.

StackedMemory(SizeEstimator backingMemorySize, Runnable logic)
Create a guest StackedMemory with an object allocation area of the size estimated by the specified SizeEstimator, bound to the specified Runnable.

StackedMemory(SizeEstimator backingMemorySize, SizeEstimator containerSize)
Create a host StackedMemory with a backing memory in a container of the sizes estimated by the specified SizeEstimators.

StackedMemory(SizeEstimator backingMemorySize, SizeEstimator containerSize, Runnable logic)
Create a host StackedMemory with a backing memory in a container of the sizes estimated by the specified SizeEstimators, bound to the specified Runnable.

Method Summary

protected void	clearMemory()
long	getMaximumSize() Get the maximum size this memory area can attain.
protected StackedMemory	getStackedHost() Find the closest parent that is a host StackedMemory.
protected boolean	hasGuest() Check if this already has a StackedMemory guest
protected boolean	isGuest() Check if this is a guest StackedMemory
protected boolean	isHost() Check if this is a host StackedMemory
protected boolean	isStackedRoot() Determines if we are in a root StackedMemory
protected StackedMemory	loadStackedParent() Load the direct parent of this StackedMemory.
long	memoryConsumed() Return the memory consumed in bytes
protected boolean	memoryNeedsToBeCleared() Checks if memory needs clearing instead of freeing
protected boolean	memoryNeedsToBeFreed() Checks if memory needs to be freed on area finalization.
void	resize(long backingMemorySize) Change the size of the backing memory for this memory area.
long	size() size returns the size of this memory area in bytes.
String	toString() toString creates a string representation of this memory area of the form "Scoped memory # "+ num with num being a unique identifier for this memory area.

Methods inherited from class javax.realtime.ScopedMemory

enter, enter, executeInArea, getParent, getPortal, getReferenceCount, join, join, joinAndEnter, joinAndEnter, joinAndEnter, joinAndEnter, setPortal

Methods inherited from class javax.realtime.MemoryArea

createStackedMemory, freeStacked, getMemoryArea, memoryRemaining, newArray, newInstance, newInstance

Methods inherited from class java.lang.Object

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

Constructor Detail

StackedMemory

public StackedMemory(long backingMemorySize,
                     long containerSize)

Create a host StackedMemory with a backing memory in a container of the specified sizes. The container is allocated from the currently active memory area if it is also a StackedMemory, and the global container otherwise. The backing memory is allocated from the container.

Parameters:

backingMemorySize - Size of the backing memory

containerSize - Size of the container

Throws:

IllegalArgumentException - when either backingMemorySize or containerSize is less than zero, or if backingMemorySize is too large to be allocated from a container of size containerSize.

OutOfMemoryError - when there is insufficient memory available to reserve the requested container.

StackedMemory

public StackedMemory(long backingMemorySize,
                     long containerSize,
                     Runnable logic)

Create a host StackedMemory with a backing memory in a container of the specified sizes, bound to the specified Runnable.. The container is allocated from the currently active memory area if it is also a StackedMemory, and the global container otherwise. The backing memory is allocated from the container.

Parameters:

backingMemorySize - Size of the backing memory

containerSize - Size of the container

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

Throws:

IllegalArgumentException - when either backingMemorySize or containerSize is less than zero, or if backingMemorySize is too large to be allocated from a container of size containerSize.

OutOfMemoryError - when there is insufficient memory available to reserve the requested container.

StackedMemory

public StackedMemory(SizeEstimator backingMemorySize,
                     SizeEstimator containerSize)

Create a host StackedMemory with a backing memory in a container of the sizes estimated by the specified SizeEstimators. The container is allocated from the currently active memory area if it is also a StackedMemory, and the global container otherwise. The backing memory is allocated from the container.

Parameters:

backingMemorySize - SizeEstimator indicating the size of the backing memory

containerSize - SizeEstimator indicating the size of the container

Throws:

IllegalArgumentException - when either backingMemorySize or containerSize is less than zero, or if backingMemorySize is too large to be allocated from a container of size containerSize.

OutOfMemoryError - when there is insufficient memory available to reserve the requested container.

StackedMemory

public StackedMemory(SizeEstimator backingMemorySize,
                     SizeEstimator containerSize,
                     Runnable logic)

Create a host StackedMemory with a backing memory in a container of the sizes estimated by the specified SizeEstimators, bound to the specified Runnable. The container is allocated from the currently active memory area if it is also a StackedMemory, and the global container otherwise. The backing memory is allocated from the container.

Parameters:

backingMemorySize - SizeEstimator indicating the size of the backing memory

containerSize - SizeEstimator indicating the size of the total container

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

Throws:

IllegalArgumentException - when either backingMemorySize or containerSize is less than zero, or if backingMemorySize is too large to be allocated from a container of size containerSize.

OutOfMemoryError - when there is insufficient memory available to reserve the requested container.

StackedMemory

public StackedMemory(long backingMemorySize)

Create a guest StackedMemory with a backing memory of the specified size. The backing memory is drawn from the container of the next parent that is not a guest.

Parameters:

backingMemorySize - Size of the backing memory

Throws:

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

IllegalArgumentException - when backingMemorySize is less than zero.

OutOfMemoryError - when there is insufficient memory available in the parent StackedMemory's container to reserve the requested backing memory.

StackedMemory

public StackedMemory(SizeEstimator backingMemorySize)

Create a guest StackedMemory with a backing memory of the size estimated by the specified SizeEstimator. The backing memory is drawn from the container of the next parent that is not a guest.

Parameters:

backingMemorySize - SizeEstimator indicating the size of the backing memory

Throws:

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

IllegalArgumentException - when backingMemorySize is less than zero.

OutOfMemoryError - when there is insufficient memory available in the parent StackedMemory's container to reserve the requested object allocation area.

StackedMemory

public StackedMemory(long backingMemorySize,
                     Runnable logic)

Create a guest StackedMemory with an object allocation area of the specified size, bound to the specified Runnable. The backing memory is drawn from the container of the next parent that is not a guest.

Parameters:

backingMemorySize - Size of the allocation area

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

Throws:

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

IllegalArgumentException - when backingMemorySize is less than zero.

OutOfMemoryError - when there is insufficient memory available in the parent StackedMemory's container to reserve the requested backing memory.

StackedMemory

public StackedMemory(SizeEstimator backingMemorySize,
                     Runnable logic)

Create a guest StackedMemory with an object allocation area of the size estimated by the specified SizeEstimator, bound to the specified Runnable. The backing memory is drawn from the container of the next parent that is not a guest.

Parameters:

backingMemorySize - SizeEstimator indicating the size of the backing memory

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

Throws:

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

IllegalArgumentException - when backingMemorySize is less than zero.

OutOfMemoryError - when there is insufficient memory available in the parent StackedMemory's container to reserve the requested object allocation area.

Method Detail

resize

public void resize(long backingMemorySize)

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

Parameters:

backingMemorySize - The new backing memory size

Throws:

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

OutOfMemoryError - when the remaining backing store is insufficient for the requested adjustment.

getMaximumSize

public long getMaximumSize()

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

Overrides:

getMaximumSize in class ScopedMemory

Returns:

The maximum size attainable.

isStackedRoot

protected boolean isStackedRoot()

Determines if we are in a root StackedMemory

Returns:

true if in root StackedMemory, false otherwise

hasGuest

protected boolean hasGuest()

Check if this already has a StackedMemory guest

Returns:

true if this already has a guest, false otherwise

getStackedHost

protected StackedMemory getStackedHost()

Find the closest parent that is a host StackedMemory. If this is a host it is always the direct parent. A guest might need to traverse multiple parents.

Returns:

the host StackedMemory lowest in the stack above this

loadStackedParent

protected StackedMemory loadStackedParent()

Load the direct parent of this StackedMemory.

Returns:

the direct parent StackedMemory

isHost

protected boolean isHost()

Check if this is a host StackedMemory

Returns:

true if host, false otherwise

isGuest

protected boolean isGuest()

Check if this is a guest StackedMemory

Returns:

true if guest, false otherwise

memoryNeedsToBeFreed

protected boolean memoryNeedsToBeFreed()

Checks if memory needs to be freed on area finalization.

Overrides:

memoryNeedsToBeFreed in class MemoryArea

Returns:

true if this is stacked root and its scoped memory needs freeing.

memoryNeedsToBeCleared

protected boolean memoryNeedsToBeCleared()

Checks if memory needs clearing instead of freeing

Overrides:

memoryNeedsToBeCleared in class MemoryArea

Returns:

true if this is not a stacked root

clearMemory

protected void clearMemory()

Overrides:

clearMemory in class MemoryArea

size

public long size()

Description copied from class: MemoryArea

size returns the size of this memory area in bytes.

Overrides:

size in class MemoryArea

Returns:

the size in bytes.

memoryConsumed

public long memoryConsumed()

Return the memory consumed in bytes

Overrides:

memoryConsumed in class MemoryArea

Returns:

the memory consumed in bytes

toString

public String toString()

Description copied from class: ScopedMemory

toString creates a string representation of this memory area of the form "Scoped memory # "+ num with num being a unique identifier for this memory area.

Overrides:

toString in class ScopedMemory

Returns:

a string representation of this.