[project @ 1999-02-01 10:19:02 by simonm]

[ghc-hetmet.git] / ghc / docs / libraries / Weak.sgml

diff --git a/ghc/docs/libraries/Weak.sgml b/ghc/docs/libraries/Weak.sgml
index 08c28af..0f223f4 100644 (file)
--- a/ghc/docs/libraries/Weak.sgml
+++ b/ghc/docs/libraries/Weak.sgml
@@ -215,6 +215,7 @@ follows
 A heap object is reachable if:
 
 <itemize>
+<item> It is a member of the <em/root set/.
 <item> It is directly pointed to by a reachable object, other than
 a weak pointer object.
 <item> It is a weak pointer object whose key is reachable.
@@ -222,6 +223,14 @@ a weak pointer object.
 reachable.
 </itemize>
 
+The root set consists of all runnable threads, and all stable pointers
+(see Section <ref id="sec:stable-pointers" name="Stable Pointers">).
+NOTE: currently all top-level objects are considered to be reachable,
+although we hope to remove this restriction in the future.  A
+<tt/Char/ or small <tt/Int/ will also be constantly reachable, since
+the garbage collector replaces heap-resident <tt/Char/s and small
+<tt/Int/s with pointers to static copies.
+
 Notice that a pointer to the key from its associated 
 value or finaliser does not make the key reachable.
 However, if the key is reachable some other way, then the value
@@ -230,6 +239,7 @@ keys they refer to directly or indirectly.
 
 
 <sect1>Finalisation for foreign objects
+<label id="foreign-finalisers">
 <p>
 
 A foreign object is some data that lives outside the Haskell heap, for
@@ -250,15 +260,14 @@ references to its key and trigger the finaliser despite the fact that
 the program still holds the <tt/Addr#/ and intends to use it.
 
 To avoid this somewhat subtle race condition, we use another type of
-foreign address, called <tt/ForeignObj/.  Historical note:
-<tt/ForeignObj/ is identical to the old <tt/ForeignObj/ except that it
-no longer supports finalisation - that's provided by the weak
+foreign address, called <tt/ForeignObj/ (see Section <ref
+id="sec:Foreign" name="Foreign">).  Historical note: <tt/ForeignObj/
+is identical to the old <tt/ForeignObj/ except that it no longer
+supports finalisation - that's provided by the weak
 pointer/finalisation mechanism above.
 
 A <tt/ForeignObj/ is basically an address, but the <tt/ForeignObj/
 itself is a heap-resident object and can therefore be watched by weak
 pointers.  A <tt/ForeignObj/ can be passed to C functions (in which
 case the C function gets a straightforward pointer), but it cannot be
-decomposed into an <tt/Addr#/.  Operations on <tt/ForeignObj/ are
-provided by the <tt/Foreign/ module (see Section <ref name="Foreign"
-id="sec:Foreign">).
+decomposed into an <tt/Addr#/.