diff options
Diffstat (limited to 'module/ice-9')
-rw-r--r-- | module/ice-9/guardians.scm | 39 |
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) |