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

diff --git a/Foreign/Concurrent.hs b/Foreign/Concurrent.hs
index 6d484e0..a914d95 100644
--- a/Foreign/Concurrent.hs
+++ b/Foreign/Concurrent.hs
@@ -1,4 +1,4 @@
-{-# OPTIONS -fno-implicit-prelude #-}
+{-# OPTIONS_GHC -XNoImplicitPrelude #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Foreign.Concurrent
@@ -9,24 +9,45 @@
 -- 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__
-	newForeignPtr,
-	addForeignPtrFinalizer,
-#endif
+        -- * 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,
   ) where
 
 #ifdef __GLASGOW_HASKELL__
+import GHC.IO           ( 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.  There is no guarantee of promptness, and
+-- in fact there is no guarantee that the finalizer will eventually
+-- run at all.
+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