From 8ac763b6076e8b027f740cae0b61171db0eb127f Mon Sep 17 00:00:00 2001 From: Taylor R Campbell Date: Tue, 27 Oct 2015 13:51:59 +0000 Subject: [PATCH] Document REFERENCE-BARRIER. --- doc/ref-manual/misc-datatypes.texi | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/ref-manual/misc-datatypes.texi b/doc/ref-manual/misc-datatypes.texi index 29b2cf090..6e843993b 100644 --- a/doc/ref-manual/misc-datatypes.texi +++ b/doc/ref-manual/misc-datatypes.texi @@ -959,6 +959,7 @@ Table}), which also holds its keys weakly. @menu * Weak Pairs:: * Ephemerons:: +* Reference barriers:: @end menu @node Weak Pairs, Ephemerons, Weak References, Weak References @@ -1054,7 +1055,7 @@ Sets the cdr component of @var{weak-pair} to @var{object} and returns an unspecified result. @end deffn -@node Ephemerons, , Weak Pairs, Weak References +@node Ephemerons, Reference barriers, Weak Pairs, Weak References @subsection Ephemerons @cindex ephemeron (defn) @@ -1140,3 +1141,21 @@ if the ephemeron is not broken is @dots{} @r{code using @var{key} and @var{datum}} @dots{})) @end group @end example + +@node Reference barriers, , Ephemerons, Weak References +@subsection Reference barriers + +@cindex reference barrier +@cindex barrier, reference +The garbage collector may break an ephemeron if it can prove that the +key is not strongly reachable. +To ensure that it does not do so before a certain point in a program, +the program can invoke a @dfn{reference barrier} on the key by +calling the @code{reference-barrier} procedure, which guarantees that +even if the program does not use the key, it will be considered +strongly reachable until after @code{reference-barrier} returns. + +@deffn procedure reference-barrier object +Guarantee that @var{object} is strongly reachable until after + @code{reference-barrier} returns. +@end deffn -- 2.25.1