The memory wordset provides dynamic run-time allocation of memory chunks. The memory chunks are allocated in a heap above the Forth application, expanding or shrinking the current slot as appropriate. Garbage collection is not provided. The initial size of the heap can be set by a command line argument. See the documentation file 'Docs.AForth' for a description of this.
Error detection is readily obtained by THROWing the ior code returned by the words described below. f.ex. '1000 ALLOCATE THROW'. See the semantic description for the Error word set for details on this.
ALLOCATE Memory
( u -- a-addr ior )
Allocate u address units (bytes) of contiguous data space. The initialisation of the allocated data space is undefined. If the allocation succeeded, a-addr is a pointer to the allocated data space and ior is zero. If the allocation failed, ior is non-zero and a-addr is invalid.
FREE Memory
( a-addr -- ior )
Return the allocated data space represented by a-addr to the system. a-addr must be a pointer to a data space previously obtained by ALLOCATE or RESIZE. If the deallocation succeeded, ior is zero, otherwise it is non-zero.
RESIZE Memory
( a-addr1 u -- a-addr2 ior )
Resize the data space represented by a-addr1 to the new size u. a-addr1 must be a pointer to a data space previously obtained by ALLOCATE or RESIZE. If the resize succeeds, ior is zero and a-addr2 is a possibly new pointer to a data space of size u. If a-addr2 has been altered, the data in the data space pointed by a-addr1 has been copied to the data space pointed by a-addr2. If the resize fails, ior is non-zero and a-addr2 is invalid. In this case, the data space represented by a-addr1 is retained.
AVAILABLE MemoryExt
( -- u )
Return the size of the largest contiguous data space that can be allocated by ALLOCATE or RESIZE. In the current implementation the value returned is the larger of the two values: the Wimp free pool or the largest free block in the heap.
