Heap Words

Heaps in zeptoforth are created by the user and consist of discretes blocks that are allocated, freed, and resized as multiples; the size of allocations plus a cell taken up by a block count is rounded up to the next full number of blocks. There is by default no global heap, and heaps created by the user are specifically not concurrency-safe; to make them concurrency-safe one must wrap them in locks, and because of the overhead this would impose, this is not done so by default. Note that the time taken up by heap allocation or resizing is bounded by a maximum which is defined by the number of blocks in the heap; any heap allocation or resizing may take this full time. On the other hand, the time taken up by freeing an allocation is determined solely by the number of blocks comprising the allocation.

heap

The following words are in heap:

heap-size

( block-size block-count – heap-bytes )

Get the size in bytes of a heap with the given block size in bytes and block count.

init-heap

( block-size block-count addr – )

Initialize a heap at addr with the given block size in bytes and block count; note that the size of the available memory at addr should be equal to or greater than the number of bytes returned by heap-size for block-size and block-count.

allocate

( size heap – addr )

Allocate memory in a heap of size bytes and return its address; if the memory cannot be allocated due to insufficient contiguous memory being available, x-allocate-failed is raised.

free

( addr heap – )

Free memory at addr in a heap.

resize

( size addr heap – new-addr )

Resize memory in a heap at addr to a new size in bytes, returning its new address. If sufficient memory is available for resizing at addr the allocation is expanded without moving or copying it and addr is returned. Otherwise, the allocation at addr is freed, and its contents is copied to a new allocation, whose address is returned. Note that if insufficient memory is available in the heap for resizing the allocation, the existing allocation is preserved, and x-allocate-failed is raised.

x-allocate-failed

( – )

This is an exception raised if allocation or resizing fails.