git.iko.soy/streamly
on ffcb268 help sign in
streamly/core/src/Streamly/Internal/Data/IOFinalizer.hs
91 lines 3.1 kB history raw
1-- |
2-- Module : Streamly.Internal.Data.IOFinalizer
3-- Copyright : (c) 2020 Composewell Technologies and Contributors
4-- License : BSD-3-Clause
5-- Maintainer : streamly@composewell.com
6-- Stability : experimental
7-- Portability : GHC
8--
9-- A value associated with an IO action that is automatically called whenever
10-- the value is garbage collected.
12module Streamly.Internal.Data.IOFinalizer
13 (
14 IOFinalizer(..)
15 , newIOFinalizer
16 , runIOFinalizer
17 , clearingIOFinalizer
18 )
19where
21import Control.Exception (mask_)
22import Control.Monad (void)
23import Control.Monad.IO.Class (MonadIO(..))
24import Data.IORef (newIORef, readIORef, mkWeakIORef, writeIORef, IORef)
26-- | An 'IOFinalizer' has an associated IO action that is automatically called
27-- whenever the finalizer is garbage collected. The action can be run and
28-- cleared prematurely.
29--
30-- You can hold a reference to the finalizer in your data structure, if the
31-- data structure gets garbage collected the finalizer will be called.
32--
33-- It is implemented using 'mkWeakIORef'.
34--
35-- /Pre-release/
36newtype IOFinalizer = IOFinalizer (IORef (Maybe (IO ())))
38-- | GC hook to run an IO action stored in a finalized IORef.
39runFinalizerGC :: IORef (Maybe (IO ())) -> IO ()
40runFinalizerGC ref = do
41 res <- readIORef ref
42 case res of
43 Nothing -> return ()
44 Just f -> f
46-- | Create a finalizer that calls the supplied function automatically when the
47-- it is garbage collected.
48--
49-- /The finalizer is always run using the state of the monad that is captured
50-- at the time of calling 'newFinalizer'./
51--
52-- Note: To run it on garbage collection we have no option but to use the monad
53-- state captured at some earlier point of time. For the case when the
54-- finalizer is run manually before GC we could run it with the current state
55-- of the monad but we want to keep both the cases consistent.
56--
57-- /Pre-release/
58newIOFinalizer :: MonadIO m => IO a -> m IOFinalizer
59newIOFinalizer finalizer = liftIO $ do
60 let f = void finalizer
61 ref <- newIORef $ Just f
62 _ <- mkWeakIORef ref (runFinalizerGC ref)
63 return $ IOFinalizer ref
65-- | Run the action associated with the finalizer and deactivate it so that it
66-- never runs again. Note, the finalizing action runs with async exceptions
67-- masked.
68--
69-- /Pre-release/
70runIOFinalizer :: MonadIO m => IOFinalizer -> m ()
71runIOFinalizer (IOFinalizer ref) = liftIO $ do
72 res <- readIORef ref
73 case res of
74 Nothing -> return ()
75 Just action -> do
76 -- if an async exception comes after writing 'Nothing' then the
77 -- finalizing action will never be run. We need to do this
78 -- atomically wrt async exceptions.
79 mask_ $ do
80 writeIORef ref Nothing
81 action
83-- | Run an action clearing the finalizer atomically wrt async exceptions. The
84-- action is run with async exceptions masked.
85--
86-- /Pre-release/
87clearingIOFinalizer :: MonadIO m => IOFinalizer -> IO a -> m a
88clearingIOFinalizer (IOFinalizer ref) action = do
89 liftIO $ mask_ $ do
90 writeIORef ref Nothing
91 action