Next: Weak References, Previous: Garbage Collection Functions, Up: Memory Management [Contents][Index]
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 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 can be freed with scm_gc_free
; however, this is not strictly
needed: 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 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
allocated with 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 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.
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
.
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
.
Allocate size bytes of automatically-managed memory. The memory is automatically freed when no longer referenced from any live memory block.
Memory allocated with scm_gc_malloc
or scm_gc_calloc
is
scanned for pointers. Memory allocated by
scm_gc_malloc_pointerless
is not scanned.
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.
Explicitly free the memory block pointed to by mem, which was
previously allocated by one of the above scm_gc
functions.
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 SMOBs.
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.
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.
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_malloc
, scm_must_realloc
and
scm_must_free
. This section explains why we want you to stop
using them, and how to do this.
The functions scm_must_malloc
and scm_must_realloc
behaved like scm_gc_malloc
and scm_gc_realloc
do now,
respectively. They would inform the GC about the newly allocated
memory via the internal equivalent of
scm_gc_register_allocation
. However,
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
calls to scm_must_free
. Additionally, there was no equivalent
to scm_malloc
, and it was tempting to just use
scm_must_malloc
and never to tell the GC that the memory has
been freed.
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.
The functions scm_done_malloc
and scm_done_free
were
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
use scm_malloc
or 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
scm_malloc
and 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 scm_must_free
or free
and
make it return zero.
The important thing is to always pair scm_malloc
with
free
; and to always pair scm_gc_malloc
with
scm_gc_free
.
The same reasoning applies to scm_must_realloc
and
scm_realloc
versus scm_gc_realloc
.
In
Guile up to version 1.8, memory allocated with scm_gc_malloc
had to be freed with scm_gc_free
.
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
(see scm_set_smob_mark
)
Next: Weak References, Previous: Garbage Collection Functions, Up: Memory Management [Contents][Index]