summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--libraries/base/Foreign/Concurrent.hs13
-rw-r--r--libraries/base/GHC/ForeignPtr.hs19
2 files changed, 22 insertions, 10 deletions
diff --git a/libraries/base/Foreign/Concurrent.hs b/libraries/base/Foreign/Concurrent.hs
index e197f798c3..94214d6b5b 100644
--- a/libraries/base/Foreign/Concurrent.hs
+++ b/libraries/base/Foreign/Concurrent.hs
@@ -38,11 +38,16 @@ 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 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
+-- reference.
+--
+-- When finalization is triggered by GC, 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.
+-- run at all for GC-triggered finalization.
+--
+-- When finalization is triggered by explicitly calling @finalizeForeignPtr@,
+-- the finalizer will run immediately on the current Haskell thread.
--
-- Note that references from a finalizer do not necessarily prevent
-- another object from being finalized. If A's finalizer refers to B
diff --git a/libraries/base/GHC/ForeignPtr.hs b/libraries/base/GHC/ForeignPtr.hs
index 0361857bcc..a076027fcb 100644
--- a/libraries/base/GHC/ForeignPtr.hs
+++ b/libraries/base/GHC/ForeignPtr.hs
@@ -237,11 +237,16 @@ newConcForeignPtr :: 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 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
+-- reference.
+--
+-- When finalization is triggered by GC, 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.
+-- run at all for GC-triggered finalization.
+--
+-- When finalization is triggered by explicitly calling @finalizeForeignPtr@,
+-- the finalizer will run immediately on the current Haskell thread.
--
-- Note that references from a finalizer do not necessarily prevent
-- another object from being finalized. If A's finalizer refers to B
@@ -402,8 +407,10 @@ addForeignPtrConcFinalizer :: ForeignPtr a -> IO () -> IO ()
-- object which have already been registered.
--
-- This is a variant of @addForeignPtrFinalizer@, where the finalizer
--- is an arbitrary @IO@ action. When it is invoked, the finalizer
--- will run in a new thread.
+-- is an arbitrary @IO@ action.
+-- When finalization is triggered by GC, the finalizer will run in a new thread.
+-- When finalization is triggered by explicitly calling @finalizeForeignPtr@,
+-- the finalizer will run immediately on the current Haskell thread.
--
-- NB. Be very careful with these finalizers. One common trap is that
-- if a finalizer references another finalized value, it does not