summaryrefslogtreecommitdiff
path: root/module/ice-9
diff options
context:
space:
mode:
Diffstat (limited to 'module/ice-9')
-rw-r--r--module/ice-9/guardians.scm39
1 files changed, 38 insertions, 1 deletions
diff --git a/module/ice-9/guardians.scm b/module/ice-9/guardians.scm
index 34e6537b9..2bc32a9fd 100644
--- a/module/ice-9/guardians.scm
+++ b/module/ice-9/guardians.scm
@@ -89,7 +89,44 @@
(define (make-guardian)
"Create a new guardian. A guardian protects a set of objects from
-garbage collection, allowing a program to apply cleanup or other"
+garbage collection, allowing a program to apply cleanup or other
+actions.
+
+@code{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 @code{#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 value 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 though of as having a strong
+reference to its associated value as long as the key is accessible.
+Consequently, when the key 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."
(define-values (push! pop!) (make-atomic-fifo))
(define (guard! obj)
(when (heap-object? obj)