Memory Management and Garbage Collection
========================================

Guile uses a garbage collector to manage most of its objects. While the garbage collector is designed to be mostly invisible, you sometimes need to interact with it explicitely.

See Garbage Collection for a general discussion of how garbage collection relates to using Guile from C.

Function related to Garbage Collection
--------------------------------------

 -- Scheme Procedure: gc
 -- C Function: scm_gc ()
     Scans all of SCM objects and reclaims for further use those that are no longer accessible.  You normally don't need to call this function explicitly.  It is called automatically when appropriate.

 -- C Function: SCM scm_gc_protect_object (SCM OBJ)
     Protects OBJ from being freed by the garbage collector, when it otherwise might be.  When you are done with the object, call scm_gc_unprotect_object on the object. Calls to scm_gc_protect/scm_gc_unprotect_object can be nested, and the object remains protected until it has been unprotected as many times as it was protected. It is an error to unprotect an object more times than it has been protected. Returns the SCM object it was passed.

 -- C Function: SCM scm_gc_unprotect_object (SCM OBJ)

     Unprotects an object from the garbage collector which was protected by scm_gc_unprotect_object. Returns the SCM object it was passed.

 -- C Function: SCM scm_permanent_object (SCM OBJ)

     Similar to scm_gc_protect_object in that it causes the collector to always mark the object, except that it should not be nested (only call scm_permanent_object on an object once), and it has no corresponding unpermanent function. Once an object is declared permanent, it will never be freed. Returns the SCM object it was passed.

 -- C Macro: void scm_remember_upto_here_1 (SCM obj)
 -- C Macro: void scm_remember_upto_here_2 (SCM obj1, SCM obj2)
     Create a reference to the given object or objects, so they're certain to be present on the stack or in a register and hence will not be freed by the garbage collector before this point.

     Note that these functions can only be applied to ordinary C local variables (ie. ``automatics'').  Objects held in global or static variables or some malloced block or the like cannot be protected with this mechanism.

 -- Scheme Procedure: gc-stats
 -- C Function: scm_gc_stats ()
     Return an association list of statistics about Guile's current use of storage.

 -- Scheme Procedure: gc-live-object-stats
 -- C Function: scm_gc_live_object_stats ()
     Return an alist of statistics of the current live objects.

 -- Function: void scm_gc_mark (SCM X)
     Mark the object X, and recurse on any objects X refers to. If X's mark bit is already set, return immediately.  This function must only be called during the mark-phase of garbage collection, typically from a smob mark function.

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 and freed with scm_gc_malloc and 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 scm_gc_free.

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 can be 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 when a dynwind context, see Dynamic Wind.

For really specialized needs, take at look at scm_gc_register_collectable_memory and scm_gc_unregister_collectable_memory.

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

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

 -- C Function: void scm_gc_register_collectable_memory (void *MEM, size_t SIZE, const char *WHAT)
     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.

 -- C Function: void scm_gc_unregister_collectable_memory (void *MEM, size_t SIZE)
     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_memory with 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.

 -- C Function: void * scm_gc_malloc (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)
     Like scm_malloc, scm_realloc or 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.

 -- C Function: void scm_gc_free (void *MEM, size_t SIZE, const char *WHAT)
     Like free, but also call scm_gc_unregister_collectable_memory.

     Note that you need to explicitely 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.

 -- C Function: void scm_frame_free (void *mem)
     Equivalent to scm_frame_unwind_handler (free, MEM, SCM_F_WIND_EXPLICITLY).  That is, the memory block at MEM will be freed when the current frame 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.

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

Weak References
---------------

[FIXME: This chapter is based on Mikael Djurfeldt's answer to a question by Michael Livshin. Any mistakes are not theirs, of course. ]

Weak references let you attach bookkeeping information to data so that the additional information automatically disappears when the original data is no longer in use and gets garbage collected. In a weak key hash, the hash entry for that key disappears as soon as the key is no longer referenced from anywhere else. For weak value hashes, the same happens as soon as the value is no longer in use. Entries in a doubly weak hash disappear when either the key or the value are not used anywhere else anymore.

Object properties offer the same kind of functionality as weak key hashes in many situations. (see Object Properties)

Here's an example (a little bit strained perhaps, but one of the examples is actually used in Guile):

Assume that you're implementing a debugging system where you want to associate information about filename and position of source code expressions with the expressions themselves.

Hashtables can be used for that, but if you use ordinary hash tables it will be impossible for the scheme interpreter to "forget" old source when, for example, a file is reloaded.

To implement the mapping from source code expressions to positional information it is necessary to use weak-key tables since we don't want the expressions to be remembered just because they are in our table.

To implement a mapping from source file line numbers to source code expressions you would use a weak-value table.

To implement a mapping from source code expressions to the procedures they constitute a doubly-weak table has to be used.

Weak hash tables
................

 -- Scheme Procedure: make-weak-key-hash-table size
 -- Scheme Procedure: make-weak-value-hash-table size
 -- Scheme Procedure: make-doubly-weak-hash-table size
 -- C Function: scm_make_weak_key_hash_table (size)
 -- C Function: scm_make_weak_value_hash_table (size)
 -- C Function: scm_make_doubly_weak_hash_table (size)
     Return a weak hash table with SIZE buckets. As with any hash table, choosing a good size for the table requires some caution.

     You can modify weak hash tables in exactly the same way you would modify regular hash tables. (see Hash Tables)

 -- Scheme Procedure: weak-key-hash-table? obj
 -- Scheme Procedure: weak-value-hash-table? obj
 -- Scheme Procedure: doubly-weak-hash-table? obj
 -- C Function: scm_weak_key_hash_table_p (obj)
 -- C Function: scm_weak_value_hash_table_p (obj)
 -- C Function: scm_doubly_weak_hash_table_p (obj)
     Return #t if OBJ is the specified weak hash table. Note that a doubly weak hash table is neither a weak key nor a weak value hash table.

Weak vectors
............

Weak vectors are mainly useful in Guile's implementation of weak hash tables.

 -- Scheme Procedure: make-weak-vector size [fill]
 -- C Function: scm_make_weak_vector (size, fill)
     Return a weak vector with SIZE elements. If the optional argument FILL is given, all entries in the vector will be set to FILL. The default value for FILL is the empty list.

 -- Scheme Procedure: weak-vector . l
 -- Scheme Procedure: list->weak-vector l
 -- C Function: scm_weak_vector (l)
     Construct a weak vector from a list: weak-vector uses the list of its arguments while list->weak-vector uses its only argument L (a list) to construct a weak vector the same way list->vector would.

 -- Scheme Procedure: weak-vector? obj
 -- C Function: scm_weak_vector_p (obj)
     Return #t if OBJ is a weak vector. Note that all weak hashes are also weak vectors.

Guardians
---------

Guardians provide a way to be notified about objects that would otherwise be collected as garbage.  Guarding them prevents the objects from being collected and cleanup actions can be performed on them, for example.

See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) "Guardians in a Generation-Based Garbage Collector".  ACM SIGPLAN Conference on Programming Language Design and Implementation, June 1993.

 -- Scheme Procedure: make-guardian
 -- C Function: scm_make_guardian ()
     Create a new guardian.  A guardian protects a set of objects from garbage collection, allowing a program to apply cleanup or other actions.

     make-guardian returns a procedure representing the guardian. Calling the guardian procedure with an argument adds the argument to the guardian's set of protected objects.  Calling the guardian procedure without an argument returns one of the protected objects which are ready for garbage collection, or #f if no such object is available.  Objects which are returned in this way are removed from the guardian.

     You can put a single object into a guardian more than once and you can put a single object into more than one guardian.  The object will then be returned multiple times by the guardian procedures.

     An object is eligible to be returned from a guardian when it is no longer referenced from outside any guardian.

     There is no guarantee about the order in which objects are returned from a guardian.  If you want to impose an order on finalization actions, for example, you can do that by keeping objects alive in some global data structure until they are no longer needed for finalizing other objects.

     Being an element in a weak vector, a key in a hash table with weak keys, or a value in a hash table with weak values does not prevent an object from being returned by a guardian.  But as long as an object can be returned from a guardian it will not be removed from such a weak vector or hash table.  In other words, a weak link does not prevent an object from being considered collectable, but being inside a guardian prevents a weak link from being broken.

     A key in a weak key hash table can be thought of as having a strong reference to its associated value as long as the key is accessible. Consequently, when the key is only accessible from within a guardian, the reference from the key to the value is also considered to be coming from within a guardian.  Thus, if there is no other reference to the value, it is eligible to be returned from a guardian.

Objects
=======

 -- Scheme Procedure: entity? obj
 -- C Function: scm_entity_p (obj)
     Return #t if OBJ is an entity.

 -- Scheme Procedure: operator? obj
 -- C Function: scm_operator_p (obj)
     Return #t if OBJ is an operator.

 -- Scheme Procedure: set-object-procedure! obj proc
 -- C Function: scm_set_object_procedure_x (obj, proc)
     Set the object procedure of OBJ to PROC. OBJ must be either an entity or an operator.

 -- Scheme Procedure: make-class-object metaclass layout
 -- C Function: scm_make_class_object (metaclass, layout)
     Create a new class object of class METACLASS, with the slot layout specified by LAYOUT.

 -- Scheme Procedure: make-subclass-object class layout
 -- C Function: scm_make_subclass_object (class, layout)
     Create a subclass object of CLASS, with the slot layout specified by LAYOUT.