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 `getAsBoolean()` and a boolean is returned.
`double`	`enter(DoubleSupplier logic)` Same as `enter(Runnable)` except that the executed method is called `getAsDouble()` and a double is returned.
`int`	`enter(IntSupplier logic)` Same as `enter(Runnable)` except that the executed method is called `getAsInt()` and an int is returned.
`long`	`enter(LongSupplier logic)` Same as `enter(Runnable)` except that the executed method is called `getAsLong()` 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)` Executes the `getAsBoolean()` method from the `logic` parameter using this memory area as the current allocation context.
`double`	`executeInArea(DoubleSupplier logic)` Executes the `getAsDouble()` method from the `logic` parameter using this memory area as the current allocation context.
`int`	`executeInArea(IntSupplier logic)` Executes the `getAsInt()` method from the `logic` parameter using this memory area as the current allocation context.
`long`	`executeInArea(LongSupplier logic)` Executes the `getAsLong()` method from the `logic` parameter using this memory area as the current allocation context.
`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)` Executes the `get()` method from the `logic` parameter using this memory area as the current allocation context.
`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 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.
`static Object`	`newArrayInArea(Object object, Class<?> type, int size)` A helper method for creating 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.
  - enter
```
public boolean enter(BooleanSupplier logic)
```
    Same as enter(Runnable) except that the executed method is called getAsBoolean() and a boolean is returned.
    
    Throws:
    
    UnsupportedOperationException - everytime, since this is not supported yet.
    
    Parameters:
    
    logic - The object whose getAsboolean() method is to be executed.
    
    Returns:
    
    the value return by the getAsBoolean() method.
  - enter
```
public double enter(DoubleSupplier logic)
```
    Same as enter(Runnable) except that the executed method is called getAsDouble() and a double is returned.
    
    Parameters:
    
    logic - The object whose getAsDouble() method is to be executed.
    
    Returns:
    
    the value return by the getAsDouble() method.
  - enter
```
public int enter(IntSupplier logic)
```
    Same as enter(Runnable) except that the executed method is called getAsInt() and an int is returned.
    
    Parameters:
    
    logic - The object whose getAsInt() method is to be executed.
    
    Returns:
    
    the value return by the getAsInt() method.
  - enter
```
public long enter(LongSupplier logic)
```
    Same as enter(Runnable) except that the executed method is called getAsLong() and a long is returned.
    
    Parameters:
    
    logic - The object whose getAsLong() method is to be executed.
    
    Returns:
    
    the value return by the getAsLong() method.
  - 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 The get() method must ensure that the returned object is allocated outside the area, when the area is not a PerennialMemory.
    
    Parameters:
    
    logic - The object whose get() method is to be executed.
    
    Returns:
    
    the value return by the get() method.
  - 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.
    
    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,
                         OutOfMemoryError,
                         StaticIllegalArgumentException
```
    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 logic whose run() method is to be executed.
  - executeInArea
```
public boolean executeInArea(BooleanSupplier logic)
```
    Executes the getAsBoolean() 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 logic whose getAsBoolean() method is to be executed.
    
    Returns:
    
    the value return by the getAsBoolean() method.
  - executeInArea
```
public double executeInArea(DoubleSupplier logic)
```
    Executes the getAsDouble() 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 logic whose getAsDouble() method is to be executed.
    
    Returns:
    
    the value return by the getAsDouble() method.
  - executeInArea
```
public int executeInArea(IntSupplier logic)
```
    Executes the getAsInt() 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 logic whose getAsInt() method is to be executed.
    
    Returns:
    
    the value return by the getAsInt() method.
  - executeInArea
```
public long executeInArea(LongSupplier logic)
```
    Executes the getAsLong() 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 logic whose getAsLong() method is to be executed.
    
    Returns:
    
    the value return by the getAsLong() method.
  - executeInArea
```
public <T> T executeInArea(Supplier<T> logic)
```
    Executes the get() 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 logic whose get() method is to be executed.
    
    Returns:
    
    the value return by the get() method.
  - 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.
    
    Returns:
    
    true only when the current memory area is also an instance of PerennialMemory.
  - mayHoldReferenceTo
```
public boolean mayHoldReferenceTo(Object value)
```
    Determines whether an object allocated in the memory area represented by this can hold a reference to the object value.
    
    Parameters:
    
    value - The object to test.
    
    Returns:
    
    does not return at the moment.
  - newArrayInArea
```
public static Object newArrayInArea(Object object,
                                    Class<?> type,
                                    int size)
                             throws StaticIllegalArgumentException,
                                    OutOfMemoryError
```
    A helper method for creating an array of type type in the memory area containing object.
    
    Throws:
    
    OutOfMemoryError
    
    StaticIllegalArgumentException
    
    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

enter

enter

enter

enter

enter

getMemoryArea

memoryConsumed

memoryRemaining

newArray

newInstance

newInstance

size

executeInArea

executeInArea

executeInArea

executeInArea

executeInArea

executeInArea

mayHoldReferenceTo

mayHoldReferenceTo

newArrayInArea