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
smob) should be allocated and freed with
scm_gc_free. The function
scm_gc_malloc will either
return a valid pointer or signal an error. It will also assume that
the new memory can be freed by a garbage collection. The garbage
collector uses this information to decide when to try to actually
collect some garbage. Memory blocks allocated with
scm_gc_malloc must be freed with
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 can be freed with
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 when a dynwind context, See Dynamic Wind.
For really specialized needs, take at look at
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
mallocfunction and can be freed with
free. There is no
scm_freefunction to go with
scm_mallocto make it easier to pass memory back and forth between different modules.
scm_callocis similar to
scm_malloc, but initializes the block of memory to zero as well.
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
freeon mem and
NULLis returned. When mem is
NULL, this function behaves like
scm_mallocand 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.
Informs the GC that the memory at mem of size size can potentially be freed during a GC. That is, announce that mem is part of a GC controlled object and when the GC happens to free that object, size bytes will be freed along with it. The GC will not free the memory itself, it will just know that so-and-so much bytes of memory are associated with GC controlled objects and the memory system figures this into its decisions when to run a GC.
mem does not need to come from
scm_malloc. You can only call this function once for every memory block.
The what argument is used for statistical purposes. It should describe the type of object that the memory will be used for so that users can identify just what strange objects are eating up their memory.
Informs the GC that the memory at mem of size size is no longer associated with a GC controlled object. You must take care to match up every call to
scm_gc_register_collectable_memorywith a call to
scm_gc_unregister_collectable_memory. If you don't do this, the GC might have a wrong impression of what is going on and run much less efficiently than it could.
scm_calloc, but also call
scm_gc_register_collectable_memory. Note that you need to pass the old size of a reallocated memory block as well. See below for a motivation.
free, but also call
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 this frees us from tracking this value in the GC itself, which will keep the memory management overhead very low.
, SCM_F_WIND_EXPLICITLY). That is, the memory block at mem will be freed when the current frame is left.
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.
Version 1.6 of Guile and earlier did not have the functions from the
previous section. In their place, it had the functions
scm_must_free. This section explains why we want you to stop
using them, and how to do this.
scm_gc_realloc do now,
respectively. They would inform the GC about the newly allocated
memory via the internal equivalent of
scm_must_free did not unregister the memory it was about to
free. The usual way to unregister memory was to return its size from
a smob free function.
This disconnectedness of the actual freeing of memory and reporting
this to the GC proved to be bad in practice. It was easy to make
mistakes and report the wrong size because allocating and freeing was
not done with symmetric code, and because it is cumbersome to compute
the total size of nested data structures that were freed with multiple
scm_must_free. Additionally, there was no equivalent
scm_malloc, and it was tempting to just use
scm_must_malloc and never to tell the GC that the memory has
The effect was that the internal statistics kept by the GC drifted out of sync with reality and could even overflow in long running programs. When this happened, the result was a dramatic increase in (senseless) GC activity which would effectively stop the program dead.
introduced to help restore balance to the force, but existing bugs did
not magically disappear, of course.
Therefore we decided to force everybody to review their code by deprecating the existing functions and introducing new ones in their place that are hopefully easier to use correctly.
For every use of
scm_must_malloc you need to decide whether to
scm_gc_malloc in its place. When the
memory block is not part of a smob or some other Scheme object whose
lifetime is ultimately managed by the garbage collector, use
free. When it is part of a smob, use
scm_gc_malloc and change the smob free function to use
scm_gc_free instead of
make it return zero.
The important thing is to always pair
free; and to always pair
The same reasoning applies to