From: Taylor R Campbell <campbell@mumble.net>
Date: Tue, 27 Oct 2015 13:51:59 +0000 (+0000)
Subject: Document REFERENCE-BARRIER.
X-Git-Tag: mit-scheme-pucked-9.2.12~376^2~27
X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=8ac763b6076e8b027f740cae0b61171db0eb127f;p=mit-scheme.git

Document REFERENCE-BARRIER.
---

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