Next: , Previous: , Up: Memory Management   [Contents][Index]

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

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.

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.

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.

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

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. Upgrading from scm_must_malloc et al.

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: , Previous: , Up: Memory Management   [Contents][Index]