Dictionary allocation is a stack-oriented allocation scheme, i.e., if you want to deallocate X, you also deallocate everything allocated after X.
The allocations using the words below are contiguous and grow the
region towards increasing addresses. Other words that allocate
dictionary memory of any kind (i.e., defining words including
:noname) in the same section end the contiguous region and
start a new one, but allocating memory in a different section does not
end a contiguous region.
In Standard Forth only created words are guaranteed to produce an
address that is the start of the following contiguous region. In
particular, the cell allocated by variable is not guaranteed to
be contiguous with following alloted memory.
You can deallocate memory by using allot with a negative argument
(with some restrictions, see allot). For larger deallocations use
marker.
here ( – addr ) core “here”
Return the address of the next free location in data space.
unused ( – u ) core-ext “unused”
Return the amount of free space remaining (in address units) in
the region addressed by here.
allot ( n – ) core “allot”
Reserve n address units of data space without initialization. n is a signed number, passing a negative n releases memory. In Forth-2012 you can only deallocate memory from the current contiguous region in this way. In Gforth you can deallocate anything in this way but named words. The system does not check this restriction.
->here ( addr – ) gforth-1.0 “to-here”
Change the value of here to addr.
c, ( c – ) core “c-comma”
Reserve data space for one char and store c in the space.
f, ( f – ) gforth-0.2 “f-comma”
Reserve data space for one floating-point number and store f in the space.
, ( w – ) core “comma”
Reserve data space for one cell and store w in the space.
2, ( w1 w2 – ) gforth-0.2 “2,”
Reserve data space for two cells and store the double w1 w2 there, w2 first (lower address).
w, ( x – ) gforth-1.0 “w-comma”
Reserve 2 bytes of data space and store the least significant 16 bits of x there.
l, ( l – ) gforth-1.0 “l-comma”
Reserve 4 bytes of data space and store the least significant 32 bits of x there.
x, ( x – ) gforth-1.0 “x-comma”
Reserve 8 bytes of data space and store (the least significant 64 bits) of x there. Reserve 8 bytes of data space and store w there.
xd, ( xd – ) gforth-1.0 “x-d-comma”
Reserve 8 bytes of data space and store the least significant 64 bits of x there.
A, ( addr – ) gforth-0.2 “A,”
Reserve data space for one cell, and store addr there. For our
cross-compiler this provides the type information necessary for a
relocatable image; normally, though, this is equivalent to
,.
mem, ( addr u – ) gforth-0.6 “mem,”
Reserve u bytes of dictionary space and copy u bytes
starting at addr there. If you want the memory to be
aligned, precede mem, with an alignment word.
save-mem-dict ( addr1 u – addr2 u ) gforth-0.7 “save-mem-dict”
Copy the memory block addr1 u to a newly alloted
memory block of size u; the target memory block starts at
addr2.
Memory accesses have to be aligned (see Address arithmetic). So of
course you should allocate memory in an aligned way, too. I.e., before
allocating a cell, here must be cell-aligned, etc.
The words below align here if it is not already. Basically it is
only already aligned for a type, if the last allocation was a multiple
of the size of this type and if here was aligned for this type
before.
After freshly createing a word, here is aligned in
Standard Forth (maxaligned in Gforth).
align ( – ) core “align”
If the data-space pointer is not aligned, reserve enough space to align it.
falign ( – ) floating “f-align”
If the data-space pointer is not float-aligned, reserve enough space to align it.
sfalign ( – ) floating-ext “s-f-align”
If the data-space pointer is not single-float-aligned, reserve enough space to align it.
dfalign ( – ) floating-ext “d-f-align”
If the data-space pointer is not double-float-aligned, reserve enough space to align it.
maxalign ( – ) gforth-0.2 “maxalign”
Align data-space pointer for all alignment requirements.