X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=Foreign%2FConcurrent.hs;h=664fa07c38c9cda97cbef2db30be7ba4c5ab6804;hb=e9e2a5412bb7cda8d13a063ac403d9f18ac97380;hp=6d484e06c9ad22dc7e95e7b759b61864c9e9482e;hpb=aeb286a558180b83258acfa65784248a0e7923ee;p=ghc-base.git

diff --git a/Foreign/Concurrent.hs b/Foreign/Concurrent.hs
index 6d484e0..664fa07 100644
--- 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