2-- Module : Streamly.Internal.Data.Stream.Exception
3-- Copyright : (c) 2019 Composewell Technologies
4-- License : BSD-3-Clause
5-- Maintainer : streamly@composewell.com
6-- Stability : experimental
9module Streamly.Internal.Data.Stream.Exception
26import Control.Exception (Exception)
27import Control.Monad.Catch (MonadCatch)
28import Control.Monad.IO.Class (MonadIO)
29import Data.Map.Strict (Map)
30import Streamly.Internal.Data.Stream.Type (Stream, fromStreamD, toStreamD)
32import qualified Streamly.Internal.Data.Stream.StreamD as D
36-- >>> import qualified Streamly.Internal.Data.Stream as Stream
38------------------------------------------------------------------------------
40------------------------------------------------------------------------------
42-- | Run the action @m b@ before the stream yields its first element.
44-- Same as the following but more efficient due to fusion:
46-- >>> before action xs = Stream.nilM action <> xs
47-- >>> before action xs = Stream.concatMap (const xs) (Stream.fromEffect action)
50before :: Monad m => m b -> Stream m a -> Stream m a
51before action xs = fromStreamD $ D.before action $ toStreamD xs
53-- | Like 'after', with following differences:
55-- * action @m b@ won't run if the stream is garbage collected
56-- after partial evaluation.
57-- * Monad @m@ does not require any other constraints.
58-- * has slightly better performance than 'after'.
60-- Same as the following, but with stream fusion:
62-- >>> after_ action xs = xs <> Stream.nilM action
67after_ :: Monad m => m b -> Stream m a -> Stream m a
68after_ action xs = fromStreamD $ D.after_ action $ toStreamD xs
70-- | Run the action @IO b@ whenever the stream stream stops normally, or
71-- if it is garbage collected after a partial lazy evaluation.
73-- The semantics of the action @IO b@ are similar to the semantics of cleanup
74-- action in 'bracketIO'.
79afterIO :: MonadIO m => IO b -> Stream m a -> Stream m a
80afterIO action xs = fromStreamD $ D.after action $ toStreamD xs
82-- | Run the action @m b@ if the stream aborts due to an exception. The
83-- exception is not caught, simply rethrown.
85-- /Inhibits stream fusion/
87{-# INLINE onException #-}
88onException :: MonadCatch m => m b -> Stream m a -> Stream m a
89onException action xs = fromStreamD $ D.onException action $ toStreamD xs
91-- | Like 'finally' with following differences:
93-- * action @m b@ won't run if the stream is garbage collected
94-- after partial evaluation.
95-- * has slightly better performance than 'finallyIO'.
97-- /Inhibits stream fusion/
101{-# INLINE finally_ #-}
102finally_ :: MonadCatch m => m b -> Stream m a -> Stream m a
103finally_ action xs = fromStreamD $ D.finally_ action $ toStreamD xs
105-- | Run the action @IO b@ whenever the stream stream stops normally, aborts
106-- due to an exception or if it is garbage collected after a partial lazy
109-- The semantics of running the action @IO b@ are similar to the cleanup action
110-- semantics described in 'bracketIO'.
112-- >>> finallyIO release = Stream.bracketIO (return ()) (const release)
114-- /See also 'finally_'/
116-- /Inhibits stream fusion/
118{-# INLINE finallyIO #-}
119finallyIO :: (MonadIO m, MonadCatch m) =>
120 IO b -> Stream m a -> Stream m a
121finallyIO action xs = fromStreamD $ D.finally action $ toStreamD xs
123-- | Like 'bracket' but with following differences:
125-- * alloc action @m b@ runs with async exceptions enabled
126-- * cleanup action @b -> m c@ won't run if the stream is garbage collected
127-- after partial evaluation.
128-- * has slightly better performance than 'bracketIO'.
130-- /Inhibits stream fusion/
134{-# INLINE bracket_ #-}
135bracket_ :: MonadCatch m
136 => m b -> (b -> m c) -> (b -> Stream m a) -> Stream m a
137bracket_ bef aft bet = fromStreamD $
138 D.bracket_ bef aft (toStreamD . bet)
140-- | Run the alloc action @IO b@ with async exceptions disabled but keeping
141-- blocking operations interruptible (see 'Control.Exception.mask'). Use the
142-- output @b@ as input to @b -> Stream m a@ to generate an output stream.
144-- @b@ is usually a resource under the IO monad, e.g. a file handle, that
145-- requires a cleanup after use. The cleanup action @b -> IO c@, runs whenever
146-- the stream ends normally, due to a sync or async exception or if it gets
147-- garbage collected after a partial lazy evaluation.
149-- 'bracketIO' only guarantees that the cleanup action runs, and it runs with
150-- async exceptions enabled. The action must ensure that it can successfully
151-- cleanup the resource in the face of sync or async exceptions.
153-- When the stream ends normally or on a sync exception, cleanup action runs
154-- immediately in the current thread context, whereas in other cases it runs in
155-- the GC context, therefore, cleanup may be delayed until the GC gets to run.
157-- /See also: 'bracket_'/
159-- /Inhibits stream fusion/
161{-# INLINE bracketIO #-}
162bracketIO :: (MonadIO m, MonadCatch m)
163 => IO b -> (b -> IO c) -> (b -> Stream m a) -> Stream m a
164bracketIO bef aft = bracket3IO bef aft aft aft
166-- For a use case of this see the "streamly-process" package. It needs to kill
167-- the process in case of exception or garbage collection, but waits for the
168-- process to terminate in normal cases.
170-- | Like 'bracketIO' but can use separate cleanup actions depending on the mode
171-- of termination. @bracket3IO before onStop onGC onException action@ runs
172-- @action@ using the result of @before@. If the stream stops, @onStop@ action
173-- is executed, if the stream is abandoned @onGC@ is executed, if the stream
174-- encounters an exception @onException@ is executed.
177{-# INLINE bracket3IO #-}
178bracket3IO :: (MonadIO m, MonadCatch m)
185bracket3IO bef aft gc exc bet = fromStreamD $
186 D.bracket' bef aft exc gc (toStreamD . bet)
188-- | Like 'handle' but the exception handler is also provided with the stream
189-- that generated the exception as input. The exception handler can thus
190-- re-evaluate the stream to retry the action that failed. The exception
191-- handler can again call 'ghandle' on it to retry the action multiple times.
193-- This is highly experimental. In a stream of actions we can map the stream
194-- with a retry combinator to retry each action on failure.
196-- /Inhibits stream fusion/
200{-# INLINE ghandle #-}
201ghandle :: (MonadCatch m, Exception e)
202 => (e -> Stream m a -> Stream m a) -> Stream m a -> Stream m a
205 . D.ghandle (\e xs -> toStreamD $ handler e (fromStreamD xs))
208-- | When evaluating a stream if an exception occurs, stream evaluation aborts
209-- and the specified exception handler is run with the exception as argument.
211-- /Inhibits stream fusion/
214handle :: (MonadCatch m, Exception e)
215 => (e -> Stream m a) -> Stream m a -> Stream m a
217 fromStreamD $ D.handle (toStreamD . handler) $ toStreamD xs
220-- | @retry@ takes 3 arguments
222-- 1. A map @m@ whose keys are exceptions and values are the number of times to
223-- retry the action given that the exception occurs.
225-- 2. A handler @han@ that decides how to handle an exception when the exception
228-- 3. The stream itself that we want to run this mechanism on.
230-- When evaluating a stream if an exception occurs,
232-- 1. The stream evaluation aborts
234-- 2. The exception is looked up in @m@
236-- a. If the exception exists and the mapped value is > 0 then,
238-- i. The value is decreased by 1.
240-- ii. The stream is resumed from where the exception was called, retrying
243-- b. If the exception exists and the mapped value is == 0 then the stream
246-- c. If the exception does not exist then we handle the exception using
252retry :: (MonadCatch m, Exception e, Ord e)
254 -- ^ map from exception to retry count
256 -- ^ default handler for those exceptions that are not in the map
259retry emap handler inp =
260 fromStreamD $ D.retry emap (toStreamD . handler) $ toStreamD inp
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list