[commit: ghc] master: Improved documentation for Foreign.Concurrent (#12547) (3a17916)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/3a17916bb5fd4bda9d21359a82f5b5f38cc0fdad/ghc

>---------------------------------------------------------------

commit 3a17916bb5fd4bda9d21359a82f5b5f38cc0fdad
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Fri Sep 16 14:48:57 2016 +0100

    Improved documentation for Foreign.Concurrent (#12547)
    
    We had better docs for the underlying functions in GHC.ForeignPtr, but
    this wasn't propagated to the re-exported versions in
    Foreign.Concurrent.


>---------------------------------------------------------------

3a17916bb5fd4bda9d21359a82f5b5f38cc0fdad
 libraries/base/Foreign/Concurrent.hs | 37 ++++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/libraries/base/Foreign/Concurrent.hs b/libraries/base/Foreign/Concurrent.hs
index 9d27166..a19b20b 100644
--- a/libraries/base/Foreign/Concurrent.hs
+++ b/libraries/base/Foreign/Concurrent.hs
@@ -35,17 +35,38 @@ import GHC.ForeignPtr ( ForeignPtr )
 import qualified GHC.ForeignPtr
 
 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
+--
+-- ^Turns a plain memory reference into a foreign object by
+-- associating a finalizer - given by the monadic operation - with the
+-- reference.  The storage manager will start the finalizer, in a
+-- separate thread, some time after the last reference to the
+-- @ForeignPtr@ is dropped.  There is no guarantee of promptness, and
 -- in fact there is no guarantee that the finalizer will eventually
 -- run at all.
+--
+-- Note that references from a finalizer do not necessarily prevent
+-- another object from being finalized.  If A's finalizer refers to B
+-- (perhaps using 'touchForeignPtr', then the only guarantee is that
+-- B's finalizer will never be started before A's.  If both A and B
+-- are unreachable, then both finalizers will start together.  See
+-- 'touchForeignPtr' for more on finalizer ordering.
+--
 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.
+-- ^This function adds a finalizer to the given @ForeignPtr at .  The
+-- finalizer will run /before/ all other finalizers for the same
+-- object which have already been registered.
+--
+-- This is a variant of @Foreign.ForeignPtr.addForeignPtrFinalizer@,
+-- where the finalizer 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@).
+--
 addForeignPtrFinalizer = GHC.ForeignPtr.addForeignPtrConcFinalizer
+