[commit: ghc] ghc-8.2: base: Improve docs to clarify when finalizers may not be run (2f96543)

[git at git.haskell.org]

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

On branch  : ghc-8.2
Link       : http://ghc.haskell.org/trac/ghc/changeset/2f9654329a5389b441d513abfd18a9e7c13b5770/ghc

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

commit 2f9654329a5389b441d513abfd18a9e7c13b5770
Author: Andrew Martin <andrew.thaddeus at gmail.com>
Date:   Thu Jul 13 11:09:34 2017 -0400

    base: Improve docs to clarify when finalizers may not be run
    
    (cherry picked from commit b066d936a919f6943de1acdc358d9e014b2cc663)


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

2f9654329a5389b441d513abfd18a9e7c13b5770
 libraries/base/System/Mem/Weak.hs | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/libraries/base/System/Mem/Weak.hs b/libraries/base/System/Mem/Weak.hs
index b9580b5..3a00696 100644
--- a/libraries/base/System/Mem/Weak.hs
+++ b/libraries/base/System/Mem/Weak.hs
@@ -67,6 +67,10 @@ module System.Mem.Weak (
         -- * A precise semantics
 
         -- $precise
+
+        -- * Implementation notes
+
+        -- $notes
    ) where
 
 import GHC.Weak
@@ -140,3 +144,25 @@ A heap object is /reachable/ if:
  * It is the value or finalizer of a weak pointer object whose key is reachable.
 -}
 
+{- $notes
+
+A finalizer is not always called after its weak pointer\'s object becomes
+unreachable. There are two situations that can cause this:
+
+ * If the object becomes unreachable right before the program exits,
+   then GC may not be performed. Finalizers run during GC, so finalizers
+   associated with the object do not run if GC does not happen.
+
+ * If a finalizer throws an exception, subsequent finalizers that had
+   been queued to run after it do not get run. This behavior may change
+   in a future release. See issue <https://ghc.haskell.org/trac/ghc/ticket/13167 13167>
+   on the issue tracker. Writing a finalizer that throws exceptions is
+   discouraged.
+
+Other than these two caveats, users can always expect that a finalizer
+will be run after its weak pointer\'s object becomes unreachable. However,
+the second caveat means that users need to trust that all of their
+transitive dependencies do not throw exceptions in finalizers, since
+any finalizers can end up queued together.
+
+-}