*** empty log message ***

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.

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?]
+Guardians provide a way to be notified about objects that would
-@deffnx {C Function} scm_make_guardian (greedy_p)
+otherwise be collected as garbage.  Guarding them prevents the objects
-Create a new guardian.
+from being collected and cleanup actions can be performed on them, for
-A guardian protects a set of objects from garbage collection,
+example.
-allowing a program to apply cleanup or other actions.
+
+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
+Calling the guardian procedure with an argument adds the argument to
-argument to the guardian's set of protected objects.
+the guardian's set of protected objects.  Calling the guardian
-Calling the guardian procedure without an argument returns
+procedure without an argument returns one of the protected objects
-one of the protected objects which are ready for garbage
+which are ready for garbage collection, or @code{#f} if no such object
-collection, or @code{#f} if no such object is available.
+is available.  Objects which are returned in this way are removed from
-Objects which are returned in this way are removed from
 the guardian.
 
-@code{make-guardian} takes one optional argument that says whether the
+You can put a single object into a guardian more than once and you can
-new guardian should be greedy or sharing.  If there is any chance
+put a single object into more than one guardian.  The object will then
-that any object protected by the guardian may be resurrected,
+be returned multiple times by the guardian procedures.
-then you should make the guardian greedy (this is the default).
 
-See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)
+An object is eligible to be returned from a guardian when it is no
-"Guardians in a Generation-Based Garbage Collector".
+longer referenced from outside any guardian.
-ACM SIGPLAN Conference on Programming Language Design
-and Implementation, June 1993.
 
-(the semantics are slightly different at this point, but the
+There is no guarantee about the order in which objects are returned
-paper still (mostly) accurately describes the interface).
+from a guardian.  If you want to impose an order on finalization
-@end deffn
+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
+Being an element in a weak vector, a key in a hash table with weak
-@deffnx {C Function} scm_destroy_guardian_x (guardian)
+keys, or a value in a hash table with weak value does not prevent an
-Destroys @var{guardian}, by making it impossible to put any more
+object from being returned by a guardian.  But as long as an object
-objects in it or get any objects from it.  It also unguards any
+can be returned from a guardian it will not be removed from such a
-objects guarded by @var{guardian}.
+weak vector or hash table.  In other words, a weak link does not
-@end deffn
+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
+A key in a weak key hash table can be though of as having a strong
-@deffnx {C Function} scm_guardian_greedy_p (guardian)
+reference to its associated value as long as the key is accessible.
-Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
+Consequently, when the key only accessible from within a guardian, the
-@end deffn
+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
-@deffn {Scheme Procedure} guardian-destroyed? guardian
+value, it is eligible to be returned from a guardian.
-@deffnx {C Function} scm_guardian_destroyed_p (guardian)
-Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
 @end deffn
 
 

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.

test-suite/ChangeLog

@@ -1,3 +1,12 @@
+2005-08-01  Marius Vollmer  <mvo@zagadka.de>
+
+
+	* 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  <mvo@zagadka.de>
 
 	* standalone/test-gh.c: Do nothing when deprecated things are