org.rigwit.forth

Class Memory

java.lang.Object

org.rigwit.forth.Memory

public class Memory
extends java.lang.Object

The memory of the Forth Virtual Machine.

This is an array of objects, mostly integers accessed by an offset. The offset is given in bytes, so must be aligned to access an individual "cell" of memory. The Cell is therefor a 32-bit value.

Characters are packed two to a cell, thus a character is is 16-bit value.

Negative offset (addresses) is an access to read only memory. This holds the input buffer and a number of "special" variables.

Field Summary

Fields

Modifier and Type	Field and Description
static int	addrBase The location of the BASE special variable.
static int	addrIn The location of the >IN special variable.
static int	addrState The location of the STATE special variable.
int	here The location of the next free location within the data space.

Constructor Summary

Constructors

Constructor and Description
Memory(VM machine, int size) Initialise the data space for the current virtual machine.

Method Summary

Methods

Modifier and Type	Method and Description
int	addCell(java.lang.Object cell) Add a cell to the data space.
int	addChar(int ch) Add a character at the data space.
int	addString(java.lang.String text) Place a counted string in memory and return its address.
static int	align(int value) Return the next cell aligned value for a given value.
void	allot(int count) Add/Remove a given number of bytes to the memory.
int	getBase() Return the current input/output base value.
int	getBufferedInput(int addr) Read a character from a given location within the input buffer.
java.lang.Object	getCell(int addr) Return the Cell at the given address within the memory.
int	getChar(int addr) Read a character from a given address in the memory.
int	getInputPosition() Return the current position in the input buffer, converted into an address.
int	getState() Return the current value of the state variable.
java.lang.String	getString(int addr) Read a counted string from the given address, returning a String.
java.lang.String	getString(int addr, int count) Read a string of count characters from memory starting at the given address.
void	setBase(int n) Change the base of the input/output.
void	setCell(int addr, java.lang.Object item) Set an cell aligned location in the memory to a given item.
void	setChar(int addr, int ch) Set the character at the character aligned address in memory to the character given.
void	setState(int state) Change the state of the compiler, to interpreting (zero) or compiling (non-zero).
int	size() Return the number of cells in the memory.

Methods inherited from class java.lang.Object

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

Field Detail

here

public int here

The location of the next free location within the data space.

addrIn

public static final int addrIn

The location of the >IN special variable.

See Also:

Constant Field Values

addrState

public static final int addrState

The location of the STATE special variable.

See Also:

Constant Field Values

addrBase

public static final int addrBase

The location of the BASE special variable.

See Also:

Constant Field Values

Constructor Detail

Memory

public Memory(VM machine,
      int size)

Initialise the data space for the current virtual machine.

Parameters:

machine - the current virtual machine.

size - the initial size of the memory.

Method Detail

size

public int size()

Return the number of cells in the memory.

Returns:

the number of cells in the memory.

setBase

public void setBase(int n)

Change the base of the input/output.

Parameters:

n - the new base value.

getBase

public int getBase()

Return the current input/output base value.

Returns:

the current base value.

getState

public int getState()

Return the current value of the state variable. This should be 0 when the system is interpreting the input and any non-zero value for compiling.

Returns:

the current interpreting state.

setState

public void setState(int state)

Change the state of the compiler, to interpreting (zero) or compiling (non-zero).

Parameters:

state - the value to place in the state variable.

align

public static int align(int value)

Return the next cell aligned value for a given value.

Parameters:

value - the value to be aligned

Returns:

the next cell aligned value.

allot

public void allot(int count)

Add/Remove a given number of bytes to the memory.

If the number is negative the memory is reclaimed. The value of the current data space pointer is updated.

Parameters:

count - the number of bytes to add/remove from memory.

addCell

public int addCell(java.lang.Object cell)

Add a cell to the data space. Align the data pointer (here) before adding the give item into the memory at the next available address.

Parameters:

cell - The Cell (Object Reference) to add into the global data store.

Returns:

The next cell aligned address after the cell was added.

getCell

public java.lang.Object getCell(int addr)
                         throws ForthException

Return the Cell at the given address within the memory. An ForthException is raised if the position is not cell-aligned.

Parameters:

addr - the address of the cell in the memory.

Returns:

the item at the cell in the memory.

Throws:

ForthException - if the address is not cell aligned, or is outside the memory range.

setCell

public void setCell(int addr,
           java.lang.Object item)
             throws ForthException

Set an cell aligned location in the memory to a given item. An exception is raised if the address is not cell aligned or if an attempt is made to write into the read only memory.

Parameters:

addr - the address in the memory to place the item.

item - the item to be placed in memory.

Throws:

ForthException - if the address is not aligned.

addChar

public int addChar(int ch)

Add a character at the data space. Align the data pointer (here) before adding the give item into the memory at the next available address.

Parameters:

ch - The character to place into memory.

Returns:

The character aligned address where the character was added.

getChar

public int getChar(int addr)
            throws ForthException

Read a character from a given address in the memory. A ForthException is raised if the address is not character aligned. As memory is stored in cells the cell must be read and split into the upper or lower haves depending on the address. Many of the value is memory will be Java object references, which can not be split. In this case the hashCode for the object is split.

Parameters:

addr - the address in memory to locate the character.

Returns:

the character from the given memory address if available.

Throws:

ForthException - if the address is not Character aligned.

setChar

public void setChar(int addr,
           int ch)
             throws ForthException

Set the character at the character aligned address in memory to the character given. A ForthException is raised if the address is not character aligned. An exception is also raised should there be an attempt to write into the read only memory, this includes:

1. the special variables, which are all cell values anyway.
2. the input buffer.

As memory is cell addressed, the cell has to be split into two and the upper or lower half replaced as indicated by the address. An exception is also raised if the item in the cell can not be split into two haves. I.e., it is an object reference.

Parameters:

addr - the address in memory to place the character.

ch - the character to be placed into memory.

Throws:

ForthException - if an attempt is made to write to the read only area (including the input buffer); the address is not character aligned; the item at the address can not be split.

getString

public java.lang.String getString(int addr)

Read a counted string from the given address, returning a String. The first character at the address is the count of the number of characters in the string.

Parameters:

addr - the location in memory to read the counted string from.

Returns:

the java located at the address.

getString

public java.lang.String getString(int addr,
                         int count)

Read a string of count characters from memory starting at the given address.

Parameters:

addr - the address in memory to find the character string

count - the number of characters in the string

Returns:

the string of characters read from memory

addString

public int addString(java.lang.String text)

Place a counted string in memory and return its address. Returns the address of the counter value of the string with the contents of the string immediately following in memory. The data pointer is advanced to the next available cell after the string.

Parameters:

text - the string to be placed into the virtual memory.

Returns:

the location of the counted string in memory.

getInputPosition

public int getInputPosition()

Return the current position in the input buffer, converted into an address. If the input reader can do this for itself we use the value it returns, otherwise we calculate the address as a character offset from the start of the negative memory address space.

Returns:

the location of the start of the input buffer.

getBufferedInput

public int getBufferedInput(int addr)
                     throws ForthException

Read a character from a given location within the input buffer. The location is converted into a character offset before being passed reading the character.

Parameters:

addr - the location to read the character from.

Returns:

the character at the given location within the input buffer.

Throws:

ForthException - if the location is outside of the input buffer.