29. Memory Management and Garbage Collection

Guile uses a garbage collector to manage most of its objects. This means that the memory used to store a Scheme string, say, is automatically reclaimed when no one is using this string any longer. This can work because Guile knows enough about its objects at run-time to be able to trace all references between them. Thus, it can find all 'live' objects (objects that are still in use) by starting from a known set of 'root' objects and following the links that these objects have to other objects, and so on. The objects that are not reached by this recursive process can be considered 'dead' and their memory can be reused for new objects.

When you are programming in Scheme, you don't need to worry about the garbage collector. When programming in C, there are a few rules that you must follow so that the garbage collector can do its job.

29.1 Garbage Collection
29.2 Weak References
29.3 Guardians

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

Scheme Procedure: gc-stats

C Function: scm_gc_stats ()

Return an association list of statistics about Guile's current use of storage.

Scheme Procedure: object-address obj

C Function: scm_object_address (obj)

Return an integer that for the lifetime of obj is uniquely returned by this function for obj

Scheme Procedure: unhash-name name

Flushes the glocs for name, or all glocs if name is #t.

Scheme Procedure: malloc-stats

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

29.2 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 section 24.2 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.

29.2.1 Weak key hashes
29.2.2 Weak vectors

29.2.1 Weak key hashes

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

Scheme Procedure: make-weak-value-hash-table k

Scheme Procedure: weak-value-hash-table? x

Scheme Procedure: make-doubly-weak-hash-table k

Scheme Procedure: doubly-weak-hash-table? x

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

29.3 Guardians

Scheme Procedure: make-guardian [greedy?]

C Function: scm_make_guardian (greedy_p)

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.

make-guardian takes one optional argument that says whether the new guardian should be greedy or sharing. If there is any chance that any object protected by the guardian may be resurrected, then you should make the guardian greedy (this is the default).

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.

(the semantics are slightly different at this point, but the paper still (mostly) accurately describes the interface).

Scheme Procedure: destroy-guardian! guardian

C Function: scm_destroy_guardian_x (guardian)

Destroys guardian, by making it impossible to put any more objects in it or get any objects from it. It also unguards any objects guarded by guardian.

Scheme Procedure: guardian-greedy? guardian

C Function: scm_guardian_greedy_p (guardian)

Return #t if guardian is a greedy guardian, otherwise #f.

Scheme Procedure: guardian-destroyed? guardian

C Function: scm_guardian_destroyed_p (guardian)

Return #t if guardian has been destroyed, otherwise #f.