5.7.2 Dictionary allocation

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) end the contiguous region and start a new one.

In ANS 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 ANS Forth 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.

c,       c –         core       “c-comma”

Reserve data space for one char and store c in the space.

f,       f –         gforth       “f,”

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       “2,”

Reserve data space for two cells and store the double w1 w2 there, w2 first (lower address).

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 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 ANS Forth (maxaligned in Gforth).

align       –         core       “align”

If the data-space pointer is not aligned, reserve enough space to align it.

falign       –         float       “f-align”

If the data-space pointer is not float-aligned, reserve enough space to align it.

sfalign       –         float-ext       “s-f-align”

If the data-space pointer is not single-float-aligned, reserve enough space to align it.

dfalign       –         float-ext       “d-f-align”

If the data-space pointer is not double-float-aligned, reserve enough space to align it.

maxalign       –         gforth       “maxalign”

Align data-space pointer for all alignment requirements.

cfalign       –         gforth       “cfalign”

Align data-space pointer for code field requirements (i.e., such that the corresponding body is maxaligned).