From 8a9a56e243e6ca15410a8b5dfe6584f9706713ba Mon Sep 17 00:00:00 2001
From: simonm <unknown>
Date: Tue, 2 Feb 1999 14:40:46 +0000
Subject: [PATCH] [project @ 1999-02-02 14:40:46 by simonm] Mention 'finalise'
 and 'mkWeakNoFinaliser'.

---
 ghc/docs/libraries/Weak.sgml |   31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/ghc/docs/libraries/Weak.sgml b/ghc/docs/libraries/Weak.sgml
index 0f223f4..80ba68b 100644
--- a/ghc/docs/libraries/Weak.sgml
+++ b/ghc/docs/libraries/Weak.sgml
@@ -19,15 +19,16 @@ module Weak (
 	-- instance Eq (Weak v)  
 
 	mkWeak,      		-- :: k -> v -> IO () -> IO (Weak v)
-	deRefWeak 		-- :: Weak v -> IO (Maybe v)
+	deRefWeak, 		-- :: Weak v -> IO (Maybe v)
+	finalise,		-- :: Weak v -> IO ()
 
 	-- Not yet implemented
-	-- finalise		-- :: Weak v -> IO ()
 	-- replaceFinaliser	-- :: Weak v -> IO () -> IO ()
 
-	mkWeakPtr 		-- :: k -> IO () -> IO (Weak k)
-	mkWeakPair 		-- :: k -> v -> IO () -> IO (Weak (k,v))
-	addFinaliser 		-- :: k -> IO () -> IO ()
+	mkWeakPtr, 		-- :: k -> IO () -> IO (Weak k)
+	mkWeakPair, 		-- :: k -> v -> IO () -> IO (Weak (k,v))
+	mkWeakNoFinaliser,	-- :: k -> v -> IO (Weak v)
+	addFinaliser, 		-- :: k -> IO () -> IO ()
 	addForeignFinaliser 	-- :: ForeignObj -> IO () -> IO ()
    ) where
 </verb></tscreen>
@@ -188,6 +189,26 @@ weak pointers:
 These more general weak pointers are enough to implement memo
 tables properly.
 
+A weak pointer can be finalised early, using the <tt/finalise/ operation:
+
+<tscreen><verb>
+finalise :: Weak v -> IO ()
+</verb></tscreen>
+
+When you don't need a finaliser, we provide the following operation:
+
+<tscreen><verb>
+mkWeakNoFinaliser :: k -> v -> IO (Weak v)
+mkWeakNoFinaliser k v = mkWeak k v (return ())
+</verb></tscreen>
+
+Which creates a weak pointer with a null finaliser.  Lots of null
+finalisers can be expensive, because each one runs in a separate
+thread, so the intention is that <tt/mkWeakNoFinaliser> avoids all the
+extra costs by generating a special kind of weak pointer without a
+finaliser.  So although the semantics of mkWeakNoFinaliser is as given
+above, its actual implementation is somewhat different.
+
 <sect1> A precise semantics
 <p>
 The above informal specification is fine for simple situations,
-- 
1.7.10.4