6.8.4 Heap allocation ¶

Heap allocation supports deallocation of allocated memory in any order. It does not affect dictionary allocation (i.e., heap allocation does not end a contiguous region). In Gforth, these words are implemented using the standard C library calls malloc(), free() and realloc().

The memory region produced by one invocation of allocate or resize is internally contiguous. There is no contiguity between such a region and any other region (including others allocated from the heap).

allocate ( u – a_addr wior  ) memory

Allocate u address units of contiguous data space. This data space is not initialized. If the allocation is successful, a-addr is the start address of the allocated region and wior is 0. If the allocation fails, a-addr is arbitrary and wior is a non-zero I/O result code.

free ( a_addr – wior  ) memory

Return the region of data space starting at a-addr to the system. The region must originally have been obtained using allocate or resize, otherwise the result of free is unpredictable. If the operation is successful, wior is 0. If the operation fails, wior is a non-zero I/O result code.

resize ( a_addr1 u – a_addr2 wior  ) memory

Change the size of the allocated area at a-addr1 to u address units, possibly moving the contents to a different area. a-addr2 is the address of the resulting area. If the operation is successful, wior is 0. If the operation fails, wior is a non-zero I/O result code. If a-addr1 is 0, Gforth’s (but not the Standard) resize allocates u address units.

• Memory blocks and heap allocation
• Growable memory buffers