Streamly.Internal.Data.Stream.Exception.Lifted

Documentation

after :: (MonadIO m, MonadBaseControl IO m) => m b -> Stream m a -> Stream m a

Run the action m b whenever the stream Stream m a stops normally, or if it is garbage collected after a partial lazy evaluation.

The semantics of the action m b are similar to the semantics of cleanup action in bracket.

See also after_

bracket :: (MonadAsync m, MonadCatch m) => m b -> (b -> m c) -> (b -> Stream m a) -> Stream m a

Run the alloc action m b with async exceptions disabled but keeping blocking operations interruptible (see mask). Use the output b as input to b -> Stream m a to generate an output stream.

b is usually a resource under the state of monad m, e.g. a file handle, that requires a cleanup after use. The cleanup action b -> m c, runs whenever the stream ends normally, due to a sync or async exception or if it gets garbage collected after a partial lazy evaluation.

bracket only guarantees that the cleanup action runs, and it runs with async exceptions enabled. The action must ensure that it can successfully cleanup the resource in the face of sync or async exceptions.

When the stream ends normally or on a sync exception, cleanup action runs immediately in the current thread context, whereas in other cases it runs in the GC context, therefore, cleanup may be delayed until the GC gets to run.

See also: bracket_

Inhibits stream fusion

bracket3 :: (MonadAsync m, MonadCatch m) => m b -> (b -> m c) -> (b -> m d) -> (b -> m e) -> (b -> Stream m a) -> Stream m a

Like bracket but can use 3 separate cleanup actions depending on the mode of termination:

1. When the stream stops normally
2. When the stream is garbage collected
3. When the stream encounters an exception

bracket3 before onStop onGC onException action runs action using the result of before. If the stream stops, onStop action is executed, if the stream is abandoned onGC is executed, if the stream encounters an exception onException is executed.

Pre-release

finally :: (MonadAsync m, MonadCatch m) => m b -> Stream m a -> Stream m a

Run the action m b whenever the stream Stream m a stops normally, aborts due to an exception or if it is garbage collected after a partial lazy evaluation.

The semantics of running the action m b are similar to the cleanup action semantics described in bracket.

>>> finally action xs = Stream.bracket (return ()) (const action) (const xs)

See also finally_

Inhibits stream fusion

retry

Arguments

:: (MonadCatch m, Exception e, Ord e)

=> Map e Int

map from exception to retry count

-> (e -> Stream m a)

default handler for those exceptions that are not in the map

-> Stream m a

-> Stream m a

retry takes 3 arguments

1. A map m whose keys are exceptions and values are the number of times to retry the action given that the exception occurs.
2. A handler han that decides how to handle an exception when the exception cannot be retried.
3. The stream itself that we want to run this mechanism on.

When evaluating a stream if an exception occurs,

1. The stream evaluation aborts
2. The exception is looked up in m

a. If the exception exists and the mapped value is > 0 then,

i. The value is decreased by 1.

ii. The stream is resumed from where the exception was called, retrying the action.

b. If the exception exists and the mapped value is == 0 then the stream evaluation stops.

c. If the exception does not exist then we handle the exception using han.

Internal

afterD :: MonadRunInIO m => m b -> Stream m a -> Stream m a

bracket3D :: (MonadAsync m, MonadCatch m) => m b -> (b -> m c) -> (b -> m d) -> (b -> m e) -> (b -> Stream m a) -> Stream m a

retryD

Arguments

:: forall e m a. (Exception e, Ord e, MonadCatch m)

=> Map e Int

map from exception to retry count

-> (e -> Stream m a)

default handler for those exceptions that are not in the map

-> Stream m a

-> Stream m a

See retry