Native Heap Management

Synopsis

(import (system heap))

Native memory allocation and deallocation utilities.

Operations

parameter: heap-allocator

A pair of native allocation and deallocation procedures. The allocation procedure should take a size and produce the address of a zeroed block of memory, the deallocation procedure consumes the address of a block previously returned by the allocation procedure.

procedure: (heap-alloc size)

procedure: (heap-alloc size wrap)

Allocates the given number of bytes using the current heap-allocator and returns two values. Before allocating, heap-collect is called to perform cleanup. Interrupts are disabled while heap-alloc runs.

If a wrapper procedure is given, the first returned value is the result of applying it to the address of the new memory block, otherwise the address is returned as is.

syntax: (heap-alloc-ftype ftype)

syntax: (heap-alloc-ftype ftype wrap)

Uses the current heap-allocator to allocate enough space for a value of ftype and returns two values. Before allocating, heap-collect is called to perform cleanup. Interrupts are disabled while heap-alloc runs.

If a wrapper procedure is given, the first returned value is the result of applying it to an ftype pointer to the new memory block, otherwise the pointer is returned as is.

The second returned value is a release procedure that deallocates the memory block, unless it has already been deallocated. Interrupts are disabled while the release procedure runs. Calling the release procedure more than once has no adverse effects.

The release procedure is also registered with a guardian and executed by heap-collect once all references to the constructed wrapper or pointer object have gone out of scope. If no wrapper was constructed or the wrapper procedure returned some atom, the release procedure itself is guarded.

procedure: (heap-register address free)

procedure: (heap-register address free wrap)

Register a dynamically allocated pointer with the heap-collect mechanism.

If a wrapper procedure is given, the first returned value is the result of applying it to the given address, otherwise the address is returned as is.

The second returned value is a release procedure that deallocates the memory block using the given free function, unless it has already been deallocated. Interrupts are disabled while the release procedure runs. Calling the release procedure more than once has no adverse effects.

The release procedure is also registered with a guardian and executed by heap-collect once all references to the constructed wrapper have gone out of scope. If no wrapper was constructed or the wrapper procedure returned some atom, the release procedure itself is guarded.

procedure: (heap-collect)

Invokes the release procedures for any memory blocks that have gone out of scope.