This is an automated email from the git hooks/post-receive script.
mdj pushed a commit to branch wip-whippet
in repository guile.
The following commit(s) were added to refs/heads/wip-whippet by this push:
new f948d414f Fixed documentation for make-guardian.
f948d414f is described below
commit f948d414f879fb48a6778037c4ceb769f03f38e7
Author: Mikael Djurfeldt <mik...@djurfeldt.com>
AuthorDate: Wed May 14 22:00:06 2025 +0200
Fixed documentation for make-guardian.
* module/ice-9/guardians.scm (make-guardian): Copy full documentation of
old C version.
---
module/ice-9/guardians.scm | 39 ++++++++++++++++++++++++++++++++++++++-
1 file changed, 38 insertions(+), 1 deletion(-)
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)
