6.19.1 Function related to Garbage Collection

Scheme Procedure: gc

C Function: scm_gc ()

Finds all of the “live” SCM objects and reclaims for further use those that are no longer accessible. You normally don’t need to call this function explicitly. Its functionality is invoked automatically as needed.

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

Note that storing obj in a C global variable has the same effect¹⁶.

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.