[project @ 2005-01-26 12:23:33 by simonmar]

[ghc-base.git] / Foreign / Concurrent.hs

diff --git a/Foreign/Concurrent.hs b/Foreign/Concurrent.hs
index 6d484e0..664fa07 100644 (file)
--- a/Foreign/Concurrent.hs
+++ b/Foreign/Concurrent.hs
@@ -1,4 +1,4 @@
-{-# OPTIONS -fno-implicit-prelude #-}
+{-# OPTIONS_GHC -fno-implicit-prelude #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Foreign.Concurrent
@@ -9,24 +9,46 @@
 -- Stability   :  provisional
 -- Portability :  non-portable (requires concurrency)
 --
--- FFI datatypes and operations that use or require concurrency.
+-- FFI datatypes and operations that use or require concurrency (GHC only).
 --
 -----------------------------------------------------------------------------
 
 module Foreign.Concurrent
   (
-       -- * Concurrency-based @ForeignPtr@ operations
-#ifdef __GLASGOW_HASKELL__
+       -- * Concurrency-based 'ForeignPtr' operations
+
+       -- | These functions generalize their namesakes in the portable
+       -- "Foreign.ForeignPtr" module by allowing arbitrary 'IO' actions
+       -- as finalizers.  These finalizers necessarily run in a separate
+       -- thread, cf. /Destructors, Finalizers and Synchronization/,
+       -- by Hans Boehm, /POPL/, 2003.
+
        newForeignPtr,
        addForeignPtrFinalizer,
-#endif
   ) where
 
 #ifdef __GLASGOW_HASKELL__
+import GHC.IOBase      ( IO )
+import GHC.Ptr         ( Ptr )
+import GHC.ForeignPtr  ( ForeignPtr )
 import qualified GHC.ForeignPtr
 #endif
 
 #ifdef __GLASGOW_HASKELL__
-newForeignPtr          = GHC.ForeignPtr.newConcForeignPtr
+newForeignPtr :: Ptr a -> IO () -> IO (ForeignPtr a)
+-- ^Turns a plain memory reference into a foreign object by associating
+-- a finalizer - given by the monadic operation - with the reference.
+-- The finalizer will be executed after the last reference to the
+-- foreign object is dropped.  Note that there is no guarantee on how
+-- soon the finalizer is executed after the last reference was dropped;
+-- this depends on the details of the Haskell storage manager.  The only
+-- guarantee is that the finalizer runs before the program terminates.
+newForeignPtr = GHC.ForeignPtr.newConcForeignPtr
+
+addForeignPtrFinalizer :: ForeignPtr a -> IO () -> IO ()
+-- ^This function adds a finalizer to the given 'ForeignPtr'.
+-- The finalizer will run after the last reference to the foreign object
+-- is dropped, but /before/ all previously registered finalizers for the
+-- same object.
 addForeignPtrFinalizer = GHC.ForeignPtr.addForeignPtrConcFinalizer
 #endif