6.2.9 Allocating memory

SCM maintains a count of bytes allocated using malloc, and calls the garbage collector when that number exceeds a dynamically managed limit. In order for this to work properly, malloc and free should not be called directly to manage memory freeable by garbage collection. The following functions are provided for that purpose:

Function: SCM must_malloc_cell (long len, SCM c, char *what)

Function: char * must_malloc (long len, char *what)

len is the number of bytes that should be allocated, what is a string to be used in error or gc messages. must_malloc returns a pointer to newly allocated memory. must_malloc_cell returns a newly allocated cell whose car is c and whose cdr is a pointer to newly allocated memory.

Function: void must_realloc_cell (SCM z, long olen, long len, char *what)

Function: char * must_realloc (char *where, long olen, long len, char *what)

must_realloc_cell takes as argument z a cell whose cdr should be a pointer to a block of memory of length olen allocated with must_malloc_cell and modifies the cdr to point to a block of memory of length len. must_realloc takes as argument where the address of a block of memory of length olen allocated by must_malloc and returns the address of a block of length len.

The contents of the reallocated block will be unchanged up to the minimum of the old and new sizes.

what is a pointer to a string used for error and gc messages.

must_malloc, must_malloc_cell, must_realloc, and must_realloc_cell must be called with interrupts deferred See Signals. must_realloc and must_realloc_cell must not be called during initialization (non-zero errjmp_bad) – the initial allocations must be large enough.

Function: void must_free (char *ptr, sizet len)

must_free is used to free a block of memory allocated by the above functions and pointed to by ptr. len is the length of the block in bytes, but this value is used only for debugging purposes. If it is difficult or expensive to calculate then zero may be used instead.