diff options
| -rw-r--r-- | libraries/base/Foreign/Concurrent.hs | 13 | ||||
| -rw-r--r-- | libraries/base/GHC/ForeignPtr.hs | 19 |
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 |