Package trivial-garbage

trivial-garbage provides a portable API to finalizers, weak hash-tables and weak pointers on all major implementations of the Common Lisp programming language. For a good introduction to these data-structures, have a look at Weak References: Data Types and Implementation by Bruno Haible.

Source code is available at github, which you are welcome to use for submitting patches and/or bug reports. Discussion takes place on trivial-garbage-devel at common-lisp.net.

About This Package

Weak Pointers
Weak Hash-Tables
Finalizers

Weak Pointers

A weak pointer holds an object in a way that does not prevent it from being reclaimed by the garbage collector. An object referenced only by weak pointers is considered unreachable (or "weakly reachable") and so may be collected at any time. When that happens, the weak pointer's value becomes nil.

Function make-weak-pointer (object)

Creates a new weak pointer which points to object. For portability reasons, object must not be nil.

Function weak-pointer-value (weak-pointer)

If weak-pointer is valid, returns its value. Otherwise, returns nil.

Function weak-pointer-p (object)

Returns true if object is a weak pointer and nil otherwise.

Weak Hash-Tables

A weak hash-table is one that weakly references its keys and/or values. When both key and value are unreachable (or weakly reachable) that pair is reclaimed by the garbage collector.

Function make-weak-hash-table (&rest args &key weakness weakness-matters &allow-other-keys)

Returns a new weak hash table. In addition to the standard arguments accepted by cl:make-hash-table, this function adds extra keywords: :weakness being the kind of weak table it should create, and :weakness-matters being whether an error should be signalled when that weakness isn't available (the default is to signal an error). weakness can be one of :key, :value, :key-or-value, :key-and-value.

If weakness is :key or :value, an entry is kept as long as its key or value is reachable, respectively. If weakness is :key-or-value or :key-and-value, an entry is kept if either or both of its key and value are reachable, respectively.

tg::make-hash-table is available as an alias for this function should you wish to import it into your package and shadow cl:make-hash-table.

Function hash-table-weakness (ht)

Returns one of nil, :key, :value, :key-or-value or :key-and-value.

Finalizers

A finalizer is a hook that is executed after a given object has been reclaimed by the garbage collector.

Function finalize (object function)

Pushes a new function to the object's list of finalizers. function should take no arguments. Returns object.

Note: function should not attempt to look at object by closing over it because that will prevent it from being garbage collected.

Function cancel-finalization (object)

Cancels all of object's finalizers, if any.

Exported Symbol Index

cancel-finalization, Function

finalize, Function

gc, Function

hash-table-weakness, Function

make-weak-hash-table, Function

make-weak-pointer, Function

weak-pointer-p, Function

weak-pointer-value, Function