In C programs, dynamic management of memory blocks is normally done with the functions malloc, realloc, and free. Guile has additional functions for dynamic memory allocation that are integrated into the garbage collector and the error reporting system.
Memory blocks that are associated with Scheme objects (for example a
foreign object) should be allocated with
scm_gc_malloc_pointerless. These two functions will either
return a valid pointer or signal an error. Memory blocks allocated this
way may be released explicitly; however, this is not strictly needed,
and we recommend not calling
scm_gc_free. All memory
is automatically reclaimed when the garbage collector no longer sees any
live reference to it16.
Memory allocated with
scm_gc_malloc is scanned for live pointers.
This means that if
scm_gc_malloc-allocated memory contains a
pointer to some other part of the memory, the garbage collector notices
it and prevents it from being reclaimed17. Conversely, memory
scm_gc_malloc_pointerless is assumed to be
“pointer-less” and is not scanned.
For memory that is not associated with a Scheme object, you can use
scm_malloc instead of
scm_gc_malloc, it will either return a valid pointer or signal
an error. However, it will not assume that the new memory block can
be freed by a garbage collection. The memory must be explicitly freed
There is also
scm_realloc, to be used
in place of
realloc when appropriate, and
scm_calloc, to be used in place of
scm_dynwind_free can be useful when memory should be
freed with libc’s
free when leaving a dynwind context,
See Dynamic Wind.
Allocate size bytes of memory and return a pointer to it. When
size is 0, return
NULL. When not enough memory is
available, signal an error. This function runs the GC to free up some
memory when it deems it appropriate.
The memory is allocated by the libc
malloc function and can be
free. There is no
scm_free function to go
scm_malloc to make it easier to pass memory back and forth
between different modules.
scm_calloc is similar to
initializes the block of memory to zero as well.
These functions will (indirectly) call
Change the size of the memory block at mem to new_size and
return its new location. When new_size is 0, this is the same
free on mem and
NULL is returned. When
NULL, this function behaves like
and allocates a new block of size new_size.
When not enough memory is available, signal an error. This function runs the GC to free up some memory when it deems it appropriate.
This function will call
Allocate size bytes of automatically-managed memory. The memory is automatically freed when no longer referenced from any live memory block.
Memory allocated with
scanned for pointers. Memory allocated by
scm_gc_malloc_pointerless is not scanned.
scm_gc_realloc call preserves the “pointerlessness” of the
memory area pointed to by mem. Note that you need to pass the old
size of a reallocated memory block as well. See below for a motivation.
Explicitly free the memory block pointed to by mem, which was
previously allocated by one of the above
scm_gc functions. This
function is almost always unnecessary, except for codebases that still
need to compile on Guile 1.8.
Note that you need to explicitly pass the size parameter. This is done since it should normally be easy to provide this parameter (for memory that is associated with GC controlled objects) and help keep the memory management overhead very low. However, in Guile 2.x, size is always ignored.
Informs the garbage collector that size bytes have been allocated, which the collector would otherwise not have known about.
In general, Scheme will decide to collect garbage only after some amount of memory has been allocated. Calling this function will make the Scheme garbage collector know about more allocation, and thus run more often (as appropriate).
It is especially important to call this function when large unmanaged allocations, like images, may be freed by small Scheme allocations, like foreign objects.
scm_dynwind_unwind_handler (free, mem,
SCM_F_WIND_EXPLICITLY). That is, the memory block at mem will be
free from the C library) when the current dynwind is
Return an alist ((what . n) ...) describing number
of malloced objects.
what is the second argument to
n is the number of objects of that type currently
This function is only available if the
preprocessor macro was defined when Guile was compiled.
In Guile up to version 1.8, memory
scm_gc_malloc had to be freed with
In Guile up to 1.8,
memory allocated with
scm_gc_malloc was not scanned.
Consequently, the GC had to be told explicitly about pointers to live
objects contained in the memory block, e.g., via SMOB mark functions