From 3a17916bb5fd4bda9d21359a82f5b5f38cc0fdad Mon Sep 17 00:00:00 2001 From: Simon Marlow Date: Fri, 16 Sep 2016 14:48:57 +0100 Subject: 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. --- 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 9d27166fde..a19b20b664 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@. 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 + -- cgit v1.2.1