From: simonmar <unknown>
Date: Fri, 16 Aug 2002 11:38:57 +0000 (+0000)
Subject: [project @ 2002-08-16 11:38:57 by simonmar]
X-Git-Tag: nhc98-1-18-release~907
X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=f3bda1126e09e570a61c7cf8ea5b6f6f589688a4;p=haskell-directory.git

[project @ 2002-08-16 11:38:57 by simonmar]
Some extra docs for addFinalizer, describing why using addFinalizer on
a ForeignPtr isn't the same as using addForeignPtrFinalizer.
---

diff --git a/GHC/Weak.lhs b/GHC/Weak.lhs
index 3ce0467..5bb710f 100644
--- a/GHC/Weak.lhs
+++ b/GHC/Weak.lhs
@@ -84,6 +84,17 @@ mkWeakPtr key finalizer = mkWeak key key finalizer
   returned is simply thrown away (however the finalizer will be
   remembered by the garbage collector, and will still be run
   when the key becomes unreachable).
+
+  Note: adding a finalizer to a 'Foreign.ForeignPtr.ForeignPtr' using
+  'addFinalizer' won't work as well as using the specialised version
+  'Foreign.ForeignPtr.addForeignPtrFinalizer' because the latter
+  version adds the finalizer to the primitive 'ForeignPtr#' object
+  inside, whereas the generic 'addFinalizer' will add the finalizer to
+  the box.  Optimisations tend to remove the box, which may cause the
+  finalizer to run earlier than you intended.  The same motivation
+  justifies the existence of
+  'Control.Concurrent.MVar.addMVarFinalizer' and
+  'Data.IORef.mkWeakIORef' (the non-unformity is accidental).
 -}
 addFinalizer :: key -> IO () -> IO ()
 addFinalizer key finalizer = do