StrongForth Memory-Allocation Glossary


ADJACENT-CHUNK ( DATA -> UNSIGNED -- 1ST )

1ST is the address of the chunk that is adjacent towards higher memory addresses to the chunk starting at DATA -> UNSIGNED. An ambiguous condition exists if DATA -> UNSIGNED is not the address of a chunk in the dynamic memory space.


ALLOCATE ( UNSIGNED -- DATA SIGNED )

Allocate UNSIGNED address units of contiguous memory space. The initial content of the allocated memory space is undefined. If the allocation succeeds, DATA is the aligned starting address of the allocated memory space and SIGNED is zero. If the operation fails, DATA does not represent a valid address and SIGNED is the I/O result code.


CALLOCATE ( UNSIGNED -- CDATA SIGNED )

Allocate UNSIGNED address units of contiguous memory space. The initial content of the allocated memory space is undefined. If the allocation succeeds, CDATA is the aligned starting address of the allocated memory space and SIGNED is zero. If the operation fails, CDATA does not represent a valid address and SIGNED is the I/O result code.


CLOBBER ( -- )

Return all chunks of dynamic memory that were previously obtained by ALLOCATE, CALLOCATE or RESIZE to the system for later allocation.


UNITS>CELLS ( UNSIGNED -- 1ST )

1ST is the minimum number of cells that can hold a memory space that spans UNSIGNED address units.


ENCLOSE-CHUNK ( DATA -> UNSIGNED -- 1ST 1ST )

1ST and 1ST are addresses of free chunks of dynamic memory. They enclose address DATA -> UNSIGNED in such a way that the first 1ST is lower than DATA -> UNSIGNED, the second 1ST is higher than DATA -> UNSIGNED, and no other free chunk exists between them. If no free chunk is available after DATA -> UNSIGNED, the second 1ST is zero.


FIND-CHUNK ( UNSIGNED -- DATA -> 1ST )

DATA -> 1ST is the address of a free chunk of dynamic memory that is at least UNSIGNED plus 2 cells long, or zero if no sufficiently long free chunk can be obtained.

Note: FIND-CHUNK does not allocate any dynamic memory.


FREE ( DATA -- SIGNED )

Return the contiguous memory space starting at DATA to the system for later allocation. DATA shall indicate a memory space that was previously obtained by ALLOCATE or RESIZE. If the operation succeeds, or DATA is null, SIGNED is zero. If the operation fails, SIGNED is the I/O result code.


FREE ( CDATA -- SIGNED )

Return the contiguous memory space starting at CDATA to the system for later allocation. CDATA shall indicate a memory space that was previously obtained by CALLOCATE or RESIZE. If the operation succeeds, or CDATA is null, SIGNED is zero. If the operation fails, SIGNED is the I/O result code.


FREELIST ( -- DATA -> UNSIGNED )

DATA -> UNSIGNED is the constant address of the first free chunk of memory that is reserved for dynamic memory allocation.


MERGE-CHUNKS ( DATA -> UNSIGNED 1ST -- )

Merge two succeeding chunks of dynamic memory starting at addresses DATA -> UNSIGNED and 1ST by increasing the size attribute of the first one by the size of the second one.


MERGE-FREE-CHUNKS ( DATA -> UNSIGNED 1ST -- )

Merge two succeeding free chunks of dynamic memory starting at addresses DATA -> UNSIGNED and 1ST by increasing the size attribute of the first one by the size of the second one. Remove the second free chunk from the linked list of free chunks.


NEXT-CHUNK ( DATA -> UNSIGNED -- DATA -> 1ST )

DATA -> 1ST is the address of a cell containing the address of the next free chunk of dynamic memory, or zero if DATA -> UNSIGNED has no successor. An ambiguous condition exists if DATA -> UNSIGNED is not the address of a free chunk.


RESIZE ( DATA UNSIGNED -- 1ST SIGNED )

Change the allocation of the contiguous memory space starting at the address DATA, previously allocated by ALLOCATE or RESIZE, to UNSIGNED address units. UNSIGNED may be either larger or smaller than the current size of the memory space. If the operation succeeds, 1ST is the aligned starting address of UNSIGNED address units of allocated memory and SIGNED is zero. 1ST may be, but need not be, the same as DATA. If they are not the same, the values contained in the memory space at DATA are copied to 1ST, up to the minimum size of either of the two memory spaces. If they are the same, the values contained in the memory space are preserved. If 1ST is not the same as DATA, the memory space at DATA is returned to the system according to the operation of FREE.

If the operation fails, 1ST equals DATA, the memory space at DATA is unaffected, and SIGNED is the I/O result code.

If DATA is zero, RESIZE just performs the semantics of ALLOCATE.


RESIZE ( CDATA UNSIGNED -- 1ST SIGNED )

Change the allocation of the contiguous memory space starting at the address CDATA, previously allocated by CALLOCATE or RESIZE, to UNSIGNED address units. UNSIGNED may be either larger or smaller than the current size of the memory space. If the operation succeeds, 1ST is the aligned starting address of UNSIGNED address units of allocated memory and SIGNED is zero. 1ST may be, but need not be, the same as CDATA. If they are not the same, the values contained in the memory space at CDATA are copied to 1ST, up to the minimum size of either of the two memory spaces. If they are the same, the values contained in the memory space are preserved. If 1ST is not the same as CDATA, the memory space at CDATA is returned to the system according to the operation of FREE.

If the operation fails, 1ST equals CDATA, the memory space at CDATA is unaffected, and SIGNED is the I/O result code.

If CDATA is zero, RESIZE just performs the semantics of CALLOCATE.


SIZE ( DATA -- UNSIGNED )

UNSIGNED is the size in address units of the contiguous memory space starting at DATA that has previously been obtained by ALLOCATE or RESIZE.


SIZE ( CDATA -- UNSIGNED )

UNSIGNED is the size in address units of the contiguous memory space starting at CDATA that has previously been obtained by CALLOCATE or RESIZE.


SIZE-FREELIST ( -- UNSIGNED )

UNSIGNED is size in cells of a region of memory that is reserved for dynamic memory allocation.


SPLIT-CHUNK ( DATA -> UNSIGNED 2ND -- 1ST )

Split a chunk of dynamic memory starting at address DATA -> UNSIGNED into two parts. The first part starts at DATA -> UNSIGNED, and its size in cells is the size of the original chunk minus 2ND. The second part starts at address 1ST, and its size in cells is equal to 2ND. An ambiguous condition exists if DATA -> UNSIGNED is not the address of a chunk or if 2ND is not lower than the size of the original chunk.


SPLIT-CHUNK' ( DATA -> UNSIGNED 2ND -- 1ST )

Split a chunk of dynamic memory starting at address DATA -> UNSIGNED into two parts. The first part starts at DATA -> UNSIGNED, and its size in cells is equal to 2ND. The second part starts at address 1ST, and its size in cells is the size of the original chunk minus 2ND. An ambiguous condition exists if DATA -> UNSIGNED is not the address of a chunk or if 2ND is not lower than the size of the original chunk.


Dr. Stephan Becher - November 22nd, 2007