[project @ 2004-09-08 11:10:08 by ross]

[ghc-base.git] / GHC / ForeignPtr.hs

diff --git a/GHC/ForeignPtr.hs b/GHC/ForeignPtr.hs
index 216f578..aa1b0e5 100644 (file)
--- a/GHC/ForeignPtr.hs
+++ b/GHC/ForeignPtr.hs
@@ -26,6 +26,7 @@ module GHC.ForeignPtr
        castForeignPtr,
        newConcForeignPtr,
        addForeignPtrConcFinalizer,
+       finalizeForeignPtr
   ) where
 
 import Control.Monad   ( sequence_ )
@@ -144,6 +145,12 @@ addForeignPtrConcFinalizer :: ForeignPtr a -> IO () -> IO ()
 -- is an arbitrary @IO@ action.  When it is invoked, the finalizer
 -- will run in a new thread.
 --
+-- NB. Be very careful with these finalizers.  One common trap is that
+-- if a finalizer references another finalized value, it does not
+-- prevent that value from being finalized.  In particular, 'Handle's
+-- are finalized objects, so a finalizer should not refer to a 'Handle'
+-- (including @stdout@, @stdin@ or @stderr@).
+--
 addForeignPtrConcFinalizer f@(ForeignPtr fo r) finalizer = do
   fs <- readIORef r
   writeIORef r (finalizer : fs)
@@ -212,7 +219,7 @@ unsafeForeignPtrToPtr :: ForeignPtr a -> Ptr a
 -- ^This function extracts the pointer component of a foreign
 -- pointer.  This is a potentially dangerous operations, as if the
 -- argument to 'unsafeForeignPtrToPtr' is the last usage
--- occurence of the given foreign pointer, then its finaliser(s) will
+-- occurrence of the given foreign pointer, then its finaliser(s) will
 -- be run, which potentially invalidates the plain pointer just
 -- obtained.  Hence, 'touchForeignPtr' must be used
 -- wherever it has to be guaranteed that the pointer lives on - i.e.,
@@ -230,3 +237,15 @@ castForeignPtr :: ForeignPtr a -> ForeignPtr b
 -- ^This function casts a 'ForeignPtr'
 -- parameterised by one type into another type.
 castForeignPtr f = unsafeCoerce# f
+
+-- | Causes a the finalizers associated with a foreign pointer to be run
+-- immediately.
+finalizeForeignPtr :: ForeignPtr a -> IO ()
+finalizeForeignPtr foreignPtr = do
+       finalizers <- readIORef refFinalizers
+       sequence_ finalizers
+       writeIORef refFinalizers []
+       where
+               refFinalizers = case foreignPtr of
+                       (ForeignPtr _ ref) -> ref
+                       (MallocPtr  _ ref) -> ref