From 930888e8e88a39cbdd081d060111993226a8499a Mon Sep 17 00:00:00 2001 From: Marius Vollmer Date: Sun, 31 Jul 2005 23:16:59 +0000 Subject: [PATCH] *** empty log message *** --- NEWS | 11 ++++++ doc/ref/api-memory.texi | 78 ++++++++++++++++++++++------------------- libguile/ChangeLog | 1 + test-suite/ChangeLog | 9 +++++ 4 files changed, 63 insertions(+), 36 deletions(-) diff --git a/NEWS b/NEWS index e762aa2d0..eb5bfc8b1 100644 --- a/NEWS +++ b/NEWS @@ -195,6 +195,17 @@ be used with '-e'. For example, you can now write a script like * Changes to Scheme functions and syntax +** Guardians have changed back to their original semantics + +Guardians now behave like described in the paper by Dybvig et al. In +particular, they no longer make guarantees about the order in which +they return objects, and they can no longer be greedy. + +They no longer drop cyclic data structures. + +The C function scm_make_guardian has been changed incompatibly and no +longer takes the 'greedy_p' argument. + ** New function hashx-remove! This function completes the set of 'hashx' functions. diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi index 0481a3851..0efffee76 100644 --- a/doc/ref/api-memory.texi +++ b/doc/ref/api-memory.texi @@ -392,50 +392,56 @@ weak hashes are also weak vectors. @node Guardians @subsection Guardians -@deffn {Scheme Procedure} make-guardian [greedy?] -@deffnx {C Function} scm_make_guardian (greedy_p) -Create a new guardian. -A guardian protects a set of objects from garbage collection, -allowing a program to apply cleanup or other actions. +Guardians provide a way to be notified about objects that would +otherwise be collected as garbage. Guarding them prevents the objects +from being collected and cleanup actions can be performed on them, for +example. + +See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) "Guardians in +a Generation-Based Garbage Collector". ACM SIGPLAN Conference on +Programming Language Design and Implementation, June 1993. + +@deffn {Scheme Procedure} make-guardian +@deffnx {C Function} scm_make_guardian () +Create a new guardian. A guardian protects a set of objects from +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 +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. -@code{make-guardian} takes one optional argument that says whether the -new guardian should be greedy or sharing. If there is any chance -that any object protected by the guardian may be resurrected, -then you should make the guardian greedy (this is the default). +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. -See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) -"Guardians in a Generation-Based Garbage Collector". -ACM SIGPLAN Conference on Programming Language Design -and Implementation, June 1993. +An object is eligible to be returned from a guardian when it is no +longer referenced from outside any guardian. -(the semantics are slightly different at this point, but the -paper still (mostly) accurately describes the interface). -@end deffn +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. -@deffn {Scheme Procedure} destroy-guardian! guardian -@deffnx {C Function} scm_destroy_guardian_x (guardian) -Destroys @var{guardian}, by making it impossible to put any more -objects in it or get any objects from it. It also unguards any -objects guarded by @var{guardian}. -@end deffn +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. -@deffn {Scheme Procedure} guardian-greedy? guardian -@deffnx {C Function} scm_guardian_greedy_p (guardian) -Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}. -@end deffn - -@deffn {Scheme Procedure} guardian-destroyed? guardian -@deffnx {C Function} scm_guardian_destroyed_p (guardian) -Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}. +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. @end deffn diff --git a/libguile/ChangeLog b/libguile/ChangeLog index 4b013b8ff..a0675ce34 100644 --- a/libguile/ChangeLog +++ b/libguile/ChangeLog @@ -20,6 +20,7 @@ (scm_i_init_guardians_for_gc, scm_i_identify_inaccessible_guardeds, scm_i_mark_inaccessible_guardeds): New. + (scm_make_guardian): Removed greedy_p argument. * weaks.h, weaks.c (SCM_I_WVECT_TYPE, SCM_I_SET_WVECT_TYPE): New. (SCM_I_WVECT_N_ITEMS, SCM_I_SET_WVECT_N_ITEMS): New. diff --git a/test-suite/ChangeLog b/test-suite/ChangeLog index 736439a52..3b0afbc9f 100644 --- a/test-suite/ChangeLog +++ b/test-suite/ChangeLog @@ -1,3 +1,12 @@ +2005-08-01 Marius Vollmer + + + * tests/weaks.test: Do not fail when the GC does not collect an + object, report it as 'unresolved'. + + * tests/guardians.test: Adapted to new (original) semantics. test + guardingobjects multiple times. + 2005-06-12 Marius Vollmer * standalone/test-gh.c: Do nothing when deprecated things are