6.19.2 Memory Blocks

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 or 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 allocated with scm_gc_malloc or scm_gc_malloc_pointerless is automatically reclaimed when the garbage collector no longer sees any live reference to it¹⁷.

When garbage collection occurs, Guile will visit the words in memory allocated with scm_gc_malloc, looking 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 reclaimed¹⁸. Conversely, memory allocated with scm_gc_malloc_pointerless is assumed to be “pointer-less” and is not scanned for pointers.

For memory that is not associated with a Scheme object, you can use scm_malloc instead of malloc. Like 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 with free.

There is also scm_gc_realloc and scm_realloc, to be used in place of realloc when appropriate, and scm_gc_calloc and scm_calloc, to be used in place of calloc when appropriate.

The function scm_dynwind_free can be useful when memory should be freed with libc’s free when leaving a dynwind context, See Dynamic Wind.

C Function: void * scm_malloc (size_t size)

C Function: void * scm_calloc (size_t size)

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 freed with free. There is no scm_free function to go with scm_malloc to make it easier to pass memory back and forth between different modules.

The function scm_calloc is similar to scm_malloc, but initializes the block of memory to zero as well.

These functions will (indirectly) call scm_gc_register_allocation.

C Function: void * scm_realloc (void *mem, size_t new_size)

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 as calling free on mem and NULL is returned. When mem is NULL, this function behaves like scm_malloc 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 scm_gc_register_allocation.

C Function: void * scm_gc_malloc (size_t size, const char *what)

C Function: void * scm_gc_malloc_pointerless (size_t size, const char *what)

C Function: void * scm_gc_realloc (void *mem, size_t old_size, size_t new_size, const char *what);

C Function: void * scm_gc_calloc (size_t size, const char *what)

Allocate size bytes of automatically-managed memory. The memory is automatically freed when no longer referenced from any live memory block.

When garbage collection occurs, Guile will visit the words in memory allocated with scm_gc_malloc or scm_gc_calloc, looking for pointers to other memory allocations that are managed by the GC. In contrast, memory allocated by scm_gc_malloc_pointerless is not scanned for pointers.

The 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.

C Function: void scm_gc_free (void *mem, size_t size, const char *what)

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.

C Function: void scm_gc_register_allocation (size_t size)

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.

C Function: void scm_dynwind_free (void *mem)

Equivalent to scm_dynwind_unwind_handler (free, mem, SCM_F_WIND_EXPLICITLY). That is, the memory block at mem will be freed (using free from the C library) when the current dynwind is left.

Scheme Procedure: malloc-stats

Return an alist ((what . n) ...) describing number of malloced objects. what is the second argument to scm_gc_malloc, n is the number of objects of that type currently allocated.

This function is only available if the GUILE_DEBUG_MALLOC preprocessor macro was defined when Guile was compiled.