MemoryArea (aicas JamaicaVM API)

java.lang.Object
- javax.realtime.MemoryArea

Direct Known Subclasses:

PerennialMemory, ScopedMemory, ScopedMemory
```
public abstract class MemoryArea
extends Object
```
MemoryArea is the abstract base class of all classes dealing with the representations of allocatable memory areas, including the immortal memory area, physical memory and scoped memory areas.
In JamaicaVM, application code is not permitted to create instances of user- defined direct subclasses of MemoryArea.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`MemoryArea(long sizeInBytes)` Equivalent to `MemoryArea(long, Runnable)` with the argument list `(size, null)`.
`protected`	`MemoryArea(long sizeInBytes, Runnable logic)` Creates an instance of `MemoryArea`.
`protected`	`MemoryArea(SizeEstimator size)` Equivalent to `MemoryArea(long, Runnable)` with the argument list `(size.getEstimate(), null)`.
`protected`	`MemoryArea(SizeEstimator size, Runnable logic)` Equivalent to `MemoryArea(long, Runnable)` with the argument list `(size.getEstimate(), logic)`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`enter()` Associates this memory area with the current schedulable for the duration of the execution of the `run()` method of the instance of `Runnable` given in the constructor.
`boolean`	`enter(BooleanSupplier logic)` Same as enter(Runnable) except that the executed method is called get and a boolean is returned.
`double`	`enter(DoubleSupplier logic)` Same as enter(Runnable) except that the executed method is called get and a double is returned.
`int`	`enter(IntSupplier logic)` Same as enter(Runnable) except that the executed method is called get and an int is returned.
`long`	`enter(LongSupplier logic)` Same as enter(Runnable) except that the executed method is called get and a long is returned.
`void`	`enter(Runnable logic)` Associates this memory area with the current schedulable for the duration of the execution of the `run()` method of the given `Runnable`.
`<T> T`	`enter(Supplier<T> logic)` Same as enter(Runnable) except that the executed method is called get and an object is returned.
`boolean`	`executeInArea(BooleanSupplier logic)` Same as executeInArea(Runnable) except that the executed method is called get and a boolean is returned.
`double`	`executeInArea(DoubleSupplier logic)` Same as executeInArea(Runnable) except that the executed method is called get and a double is returned.
`int`	`executeInArea(IntSupplier logic)` Same as executeInArea(Runnable) except that the executed method is called get and an int is returned.
`long`	`executeInArea(LongSupplier logic)` Same as executeInArea(Runnable) except that the executed method is called get and a long is returned.
`void`	`executeInArea(Runnable logic)` Executes the `run()` method from the `logic` parameter using this memory area as the current allocation context.
`<T> T`	`executeInArea(Supplier<T> logic)` Same as executeInArea(Runnable) except that the executed method is called get and an object is returned.
`static MemoryArea`	`getMemoryArea(Object object)` Gets the `MemoryArea` in which the given object is located.
`boolean`	`mayHoldReferenceTo()` Determines whether an object A allocated in the memory area represented by this can hold a reference to an object B allocated in the current memory area.
`boolean`	`mayHoldReferenceTo(Object value)` Determines whether an object A allocated in the memory area represented by this can hold a reference to the object value.
`long`	`memoryConsumed()` For memory areas where memory is freed under program control this returns an exact count, in bytes, of the memory currently used by the system for the allocated objects.
`long`	`memoryRemaining()` An approximation of the total amount of memory currently available for future allocated objects, measured in bytes.
`Object`	`newArray(Class<?> type, int number)` Allocates an array of the given type in this memory area.
`Object`	`newArrayInArea(Object object, Class<?> type, int size)` A helper method to create an array of type type in the memory area containing object.
`<T> T`	`newInstance(Class<T> type)` Allocates an object in this memory area.
`<T> T`	`newInstance(Constructor<T> c, Object[] args)` Allocates a new instance using the given constructor and passing arguments to this constructor.
`long`	`size()` Queries the size of the memory area.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - MemoryArea
```
protected MemoryArea(long sizeInBytes)
```
    Equivalent to MemoryArea(long, Runnable) with the argument list (size, null).
    
    Throws:
    
    StaticIllegalArgumentException - when size is less than zero.
    
    OutOfMemoryError - when there is insufficient memory for the MemoryArea object or for its allocation area in its backing store.
    
    UnsupportedOperationException - in JamaicaVM when a user-defined subclass does not know about the memory area implementation details.
    
    Parameters:
    
    sizeInBytes - The size of MemoryArea to allocate, in bytes.
  - MemoryArea
```
protected MemoryArea(SizeEstimator size)
```
    Equivalent to MemoryArea(long, Runnable) with the argument list (size.getEstimate(), null).
    
    Throws:
    
    StaticIllegalArgumentException - when the size parameter is null, or size.getEstimate() is negative.
    
    OutOfMemoryError - when there is insufficient memory for the MemoryArea object or for its allocation area in its backing store.
    
    UnsupportedOperationException - in JamaicaVM when a user-defined subclass does not know about the memory area implementation details.
    
    Parameters:
    
    size - A SizeEstimator object which indicates the amount of memory required by this MemoryArea.
  - MemoryArea
```
protected MemoryArea(long sizeInBytes,
                     Runnable logic)
```
    Creates an instance of MemoryArea.
    
    Throws:
    
    StaticIllegalArgumentException - when the size parameter is less than zero.
    
    OutOfMemoryError - when there is insufficient memory for the MemoryArea object or for its allocation area in its backing store.
    
    IllegalAssignmentError - when storing logic in this would violate the assignment rules.
    
    UnsupportedOperationException - in JamaicaVM when a user-defined subclass does not know about the memory area implementation details.
    
    Parameters:
    
    sizeInBytes - The size of MemoryArea to allocate, in bytes.
    
    logic - A runnable, whose run() method will be called whenever enter() is called. When logic is null, this constructor is equivalent to MemoryArea(long size).
  - MemoryArea
```
protected MemoryArea(SizeEstimator size,
                     Runnable logic)
```
    Equivalent to MemoryArea(long, Runnable) with the argument list (size.getEstimate(), logic).
    
    Throws:
    
    StaticIllegalArgumentException - when size is null or size.getEstimate() is negative.
    
    OutOfMemoryError - when there is insufficient memory for the MemoryArea object or for its allocation are in its backing store.
    
    IllegalAssignmentError - when storing logic in this would violate the assignment rules.
    
    UnsupportedOperationException - in JamaicaVM when a user-defined subclass does not know about the memory area implementation details.
    
    Parameters:
    
    size - A SizeEstimator object which indicates the amount of memory required by this MemoryArea.
    
    logic - A runnable, whose run() method will be called whenever enter() is called. When logic is null, this constructor is equivalent to MemoryArea(SizeEstimator size).
- Method Detail
  - enter
```
public void enter()
```
    Associates this memory area with the current schedulable for the duration of the execution of the 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.
    
    Throws:
    
    IllegalTaskStateException - when the caller context is not an instance of Schedulable.
    
    StaticIllegalArgumentException - when the caller is a schedulable and a null value for logic was supplied when the memory area was constructed.
    
    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 instance is preallocated by the VM to avoid cascading creation of ThrowBoundaryError.
    
    MemoryAccessError - when caller is a schedulable that may not use the heap and this memory area's logic value is allocated in heap memory.
  - enter
```
public void enter(Runnable logic)
```
    Associates this memory area with the current schedulable for the duration of the execution 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 (using enter, or executeInArea(java.lang.Runnable)) or the enter method exits.
    
    Throws:
    
    IllegalTaskStateException - when the caller context is not an instance of Schedulable.
    
    StaticIllegalArgumentException - when the caller is a schedulable and logic is null.
    
    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 instance is preallocated by the VM to avoid cascading creation of ThrowBoundaryError.
    
    Parameters:
    
    logic - The Runnable object whose run() method should be invoked.
  - getMemoryArea
```
public static MemoryArea getMemoryArea(Object object)
```
    Gets the MemoryArea in which the given object is located.
    
    Throws:
    
    StaticIllegalArgumentException - when the value of object is null.
    
    Parameters:
    
    object - the object, must not be null.
    
    Returns:
    
    the instance of MemoryArea from which object was allocated.
  - memoryConsumed
```
public long memoryConsumed()
```
    For memory areas where memory is freed under program control this returns an exact count, in bytes, of the memory currently used by the system for the allocated objects. For memory areas (such as heap) where the definition of "used" is imprecise, this returns the best value it can generate in constant time.
    In JamaicaVM, the memoryConsumed() for HeapMemory is amount of allocated (i.e., non-free) memory. It is an upper bound for the amount of reachable memory.
    
    Returns:
    
    the amount of remaining memory in bytes.
  - memoryRemaining
```
public long memoryRemaining()
```
    An approximation of the total amount of memory currently available for future allocated objects, measured in bytes.
    In JamaicaVM, memoryRemaining for HeapMemory is the total heap memory minus memoryConsumed().
    
    Returns:
    
    the amount of remaining memory in bytes.
  - newArray
```
public Object newArray(Class<?> type,
                       int number)
                throws StaticIllegalArgumentException,
                       OutOfMemoryError
```
    Allocates an array of the given type in this memory area. This method may be concurrently used by multiple threads.
    In JamaicaVM this method is save to be used concurrently by several threads, it synchronizes on this.
    
    Throws:
    
    StaticIllegalArgumentException - when number is less than zero, type is null, or type is java.lang.Void.TYPE.
    
    OutOfMemoryError - when space in the memory area is exhausted.
    
    SecurityException - when the caller does not have permission to create a new instance.
    
    Parameters:
    
    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.
    
    Returns:
    
    a new array of class type, of number elements.
  - newInstance
```
public <T> T newInstance(Class<T> type)
                  throws IllegalAccessException,
                         InstantiationException
```
    Allocates an object in this memory area. This method may be concurrently used by multiple threads.
    
    Throws:
    
    IllegalAccessException - thrown if class or constructor is inaccessible.
    
    StaticIllegalArgumentException - iff type is null.
    
    InstantiationException - if object could not be instantiated (due to type being abstract or an interface or the constructor caused an exception)
    
    OutOfMemoryError - iff the space in this memory area is exhausted
    
    ExceptionInInitializerError - iff initialization of class type caused an exception.
    
    InaccessibleAreaException - iff this memory area is not accessible, i.e. not on the memory area stack.
    
    Type Parameters:
    
    T - The type of the created object
    
    Parameters:
    
    type - the type of the new object that is to be allocated.
    
    Returns:
    
    the new instance allocated from this memory area.
  - newInstance
```
public <T> T newInstance(Constructor<T> c,
                         Object[] args)
                  throws IllegalAccessException,
                         InstantiationException,
                         InvocationTargetException
```
    Allocates a new instance using the given constructor and passing arguments to this constructor.
    
    Throws:
    
    IllegalAccessException - thrown if type is inaccessible
    
    StaticIllegalArgumentException - iff c is null or args does not contain the number of arguments required by c (args may be null if the arguments list is empty).
    
    InstantiationException - if object could not be instantiated (due to type being abstract or an interface or the constructor caused an exception)
    
    OutOfMemoryError - iff the space in this memory area is exhausted
    
    ExceptionInInitializerError - iff initialization of class type caused an exception.
    
    InaccessibleAreaException - iff this memory area is not accessible, i.e. not on the memory area stack.
    
    InvocationTargetException
    
    Type Parameters:
    
    T - The type of the created object
    
    Parameters:
    
    c - the constructor of the new instance
    
    args - the arguments to be passed to the constructor
    
    Returns:
    
    the new instance allocated from this memory area.
  - size
```
public long size()
```
    Queries the size of the memory area. The returned value is the current size. The current size may be larger than initial size for those areas that are allowed to grow.
    
    Returns:
    
    the size of the memory area in bytes.
  - executeInArea
```
public void executeInArea(Runnable logic)
```
    Executes the run() method from the logic parameter using this memory area as the current allocation context. The effect of executeInArea on the scope stack is specified in the subclasses of MemoryArea.
    
    Throws:
    
    StaticIllegalArgumentException - when logic is null.
    
    Parameters:
    
    logic - The runnable object whose run() method should be executed.
  - enter
```
public boolean enter(BooleanSupplier logic)
```
    Same as enter(Runnable) except that the executed method is called get and a boolean is returned.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    does not return at the Moment.
  - enter
```
public int enter(IntSupplier logic)
```
    Same as enter(Runnable) except that the executed method is called get and an int is returned.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    does not return at the Moment.
  - enter
```
public long enter(LongSupplier logic)
```
    Same as enter(Runnable) except that the executed method is called get and a long is returned.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    does not return at the Moment.
  - enter
```
public double enter(DoubleSupplier logic)
```
    Same as enter(Runnable) except that the executed method is called get and a double is returned.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    does not return at the Moment.
  - enter
```
public <T> T enter(Supplier<T> logic)
```
    Same as enter(Runnable) except that the executed method is called get and an object is returned. The Supplier.get() method must ensure that the returned object is allocated outside the area, when the area is not a PerennialMemory.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    does not return at the Moment.
  - executeInArea
```
public <T> T executeInArea(Supplier<T> logic)
```
    Same as executeInArea(Runnable) except that the executed method is called get and an object is returned. For a memory are that is not a PerennialMemory, care must be taken that the returned value is assignable to an object allocated in the current area.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is v.
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    does not return at the Moment.
  - executeInArea
```
public boolean executeInArea(BooleanSupplier logic)
```
    Same as executeInArea(Runnable) except that the executed method is called get and a boolean is returned.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    does not return at the Moment.
  - executeInArea
```
public int executeInArea(IntSupplier logic)
```
    Same as executeInArea(Runnable) except that the executed method is called get and an int is returned.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    does not return at the Moment.
  - executeInArea
```
public long executeInArea(LongSupplier logic)
```
    Same as executeInArea(Runnable) except that the executed method is called get and a long is returned.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    does not return at the Moment.
  - executeInArea
```
public double executeInArea(DoubleSupplier logic)
```
    Same as executeInArea(Runnable) except that the executed method is called get and a double is returned.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    logic - The object whose get method will be executed.
    
    Returns:
    
    does not return at the Moment.
  - mayHoldReferenceTo
```
public boolean mayHoldReferenceTo()
```
    Determines whether an object A allocated in the memory area represented by this can hold a reference to an object B allocated in the current memory area.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Returns:
    
    does not return at the moment.
  - mayHoldReferenceTo
```
public boolean mayHoldReferenceTo(Object value)
```
    Determines whether an object A allocated in the memory area represented by this can hold a reference to the object value.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    value - The object to test.
    
    Returns:
    
    does not return at the moment.
  - newArrayInArea
```
public Object newArrayInArea(Object object,
                             Class<?> type,
                             int size)
```
    A helper method to create an array of type type in the memory area containing object.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    object - is the reference for determining the area in which to allocate the array.
    
    type - is the type of the array element for the returned array.
    
    size - is the size of the array to return.
    
    Returns:
    
    does not return at the moment.

Class MemoryArea

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MemoryArea

MemoryArea

MemoryArea

MemoryArea

Method Detail

enter

enter

getMemoryArea

memoryConsumed

memoryRemaining

newArray

newInstance

newInstance

size

executeInArea

enter

enter

enter

enter

enter

executeInArea

executeInArea

executeInArea

executeInArea

executeInArea

mayHoldReferenceTo

mayHoldReferenceTo

newArrayInArea