6.41 Interfacing with garbage collection

Function: collect

Function: collect requested-generation

Explicitly run the garbage collector. If post–garbage collection hooks are registered, they are run. This function does not care if automatic garbage collection is disabled.

The optional argument requested-generation represents the oldest objects generation to collect: when #f the generation is determined internally; when a fixnum between 0 inclusive and 4 inclusive the fixnum represents the generation, where 0 is the youngest generation and 4 is the oldest generation. The symbol ‘fastest’ is equivalent to 0, the symbol ‘fullest’ is equivalent to 4.

Function: automatic-collect

Function: automatic-collect requested-generation

Like collect, but does care if automatic garbage collection is disabled. This function exists mostly for debugging purposes, to track what happens when automatic garbage collection is disabled and the collector is invoked.

Function: automatic-garbage-collection

Function: automatic-garbage-collection obj

When called with one argument: if obj is #f, disable automatic garbage collection; otherwise enable it. Return a boolean: #t if automatic garbage collection is enabled; #f otherwise.

When called without arguments, return a boolean: #t if automatic garbage collection is enabled, #f otherwise.

When automatic garbage collection is disabled: every memory allocation for Scheme objects is performed by enlarging, when needed, the Scheme heap’s nursery.

We must use with care this function, possibly in conjunction with collect: explicitly calling collect will still perform garbage collection even when the automatic one is disabled.

Strictly speaking, this function is not a parameter, but its API is compatible with the one of parameters; so it is possible to use it in a parametrise syntax:

(parametrise ((automatic-garbage-collection #f))
  ?body)

Avoiding garbage collection of objects

The following API allows us to register objects in the internal state of Vicare so that they are not garbage collected even though we may loose all the Scheme references to them.

This mechanism is useful when we create a Scheme object and register it in a data structure controlled by a foreign library (for example when interfacing with C language libraries); we can loose the Scheme references to such object without having it garbage collected, and later we retrieve the object reference and use it.

Function: register-to-avoid-collecting obj

Register obj in the internal state of Vicare so that it is not garbage collected even when we loose all the Scheme references to it; return a pointer object which can be used to uniquely identify the collected obj.

If obj is the return value of (void): the returned value is a NULL pointer.

Function: forget-to-avoid-collecting pointer

Remove the Scheme object associated to pointer from the internal state of Vicare, so that it is garbage collected when we loose all the Scheme references to it; return the referenced object. pointer must be the return value of a previous call to register-to-avoid-collecting.

If pointer is NULL: nothing happens and the returned value is (void).

Function: retrieve-to-avoid-collecting pointer

Return the Scheme object associated to pointer in the internal state of Vicare. pointer must be the return value of a previous call to register-to-avoid-collecting.

If pointer is NULL: nothing happens and the returned value is (void).

Function: replace-to-avoid-collecting pointer new-obj

Replace the Scheme object associated to pointer in the internal state of Vicare with new-obj; return the previously registered object. pointer must be the return value of a previous call to register-to-avoid-collecting.

If pointer is NULL: nothing happens and the returned value is (void).

Function: collection-avoidance-list

Return the list of objects that where registered to avoid collection by register-to-avoid-collecting; it can be the empty list.

Function: purge-collection-avoidance-list

Reset to empty the list of objects registered to avoid collection with register-to-avoid-collecting. Use with care.