Update Trac ticket URLs to point to GitLab
[ghc.git] / libraries / base / System / Mem / Weak.hs
index 71b8446..8d21eb5 100644 (file)
@@ -1,12 +1,11 @@
 {-# LANGUAGE Trustworthy #-}
-{-# LANGUAGE CPP #-}
 
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  System.Mem.Weak
 -- Copyright   :  (c) The University of Glasgow 2001
 -- License     :  BSD-style (see the file libraries/base/LICENSE)
--- 
+--
 -- Maintainer  :  libraries@haskell.org
 -- Stability   :  experimental
 -- Portability :  non-portable
@@ -17,9 +16,9 @@
 -- object.  A weak pointer can be de-referenced to find out
 -- whether the object it refers to is still alive or not, and if so
 -- to return the object itself.
--- 
+--
 -- Weak pointers are particularly useful for caches and memo tables.
--- To build a memo table, you build a data structure 
+-- To build a memo table, you build a data structure
 -- mapping from the function argument (the key) to its result (the
 -- value).  When you apply the function to a new argument you first
 -- check whether the key\/value pair is already in the memo table.
 -- key and value alive.  So the table should contain a weak pointer
 -- to the key, not an ordinary pointer.  The pointer to the value must
 -- not be weak, because the only reference to the value might indeed be
--- from the memo table.   
--- 
+-- from the memo table.
+--
 -- So it looks as if the memo table will keep all its values
 -- alive for ever.  One way to solve this is to purge the table
 -- occasionally, by deleting entries whose keys have died.
--- 
+--
 -- The weak pointers in this library
 -- support another approach, called /finalization/.
 -- When the key referred to by a weak pointer dies, the storage manager
 -- arranges to run a programmer-specified finalizer.  In the case of memo
 -- tables, for example, the finalizer could remove the key\/value pair
--- from the memo table.  
--- 
+-- from the memo table.
+--
 -- Another difficulty with the memo table is that the value of a
 -- key\/value pair might itself contain a pointer to the key.
 -- So the memo table keeps the value alive, which keeps the key alive,
 -- even though there may be no other references to the key so both should
--- die.  The weak pointers in this library provide a slight 
+-- die.  The weak pointers in this library provide a slight
 -- generalisation of the basic weak-pointer idea, in which each
 -- weak pointer actually contains both a key and a value.
 --
 -----------------------------------------------------------------------------
 
 module System.Mem.Weak (
-       -- * The @Weak@ type
-       Weak,                   -- abstract
-
-       -- * The general interface
-       mkWeak,                 -- :: k -> v -> Maybe (IO ()) -> IO (Weak v)
-       deRefWeak,              -- :: Weak v -> IO (Maybe v)
-       finalize,               -- :: Weak v -> IO ()
-
-       -- * Specialised versions
-       mkWeakPtr,              -- :: k -> Maybe (IO ()) -> IO (Weak k)
-       addFinalizer,           -- :: key -> IO () -> IO ()
-       mkWeakPair,             -- :: k -> v -> Maybe (IO ()) -> IO (Weak (k,v))
-       -- replaceFinaliser     -- :: Weak v -> IO () -> IO ()
-
-       -- * A precise semantics
-       
-       -- $precise
-   ) where
+        -- * The @Weak@ type
+        Weak,                   -- abstract
+
+        -- * The general interface
+        mkWeak,
+        deRefWeak,
+        finalize,
+
+        -- * Specialised versions
+        mkWeakPtr,
+        addFinalizer,
+        mkWeakPair,
+        -- replaceFinaliser
+
+        -- * A precise semantics
 
-#ifdef __HUGS__
-import Hugs.Weak
-import Prelude
-#endif
+        -- $precise
+
+        -- * Implementation notes
+
+        -- $notes
+   ) where
 
-#ifdef __GLASGOW_HASKELL__
 import GHC.Weak
-#endif
 
 -- | A specialised version of 'mkWeak', where the key and the value are
 -- the same object:
@@ -148,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://gitlab.haskell.org/ghc/ghc/issues/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.
+
+-}