Control.Pipe.Exception

Documentation

throw :: (Monad m, Exception e) => e -> Pipe a b m r

Throw an exception within the Pipe monad.

An exception thrown with throw can be caught by catch with any base monad.

If the exception is not caught in the Pipeline at all, it will be rethrown as a normal Haskell exception when using runPipe. Note that runPurePipe returns the exception in an Either value, instead.

catch

Arguments

:: (Monad m, Exception e)

=> Pipe a b m r

Pipe to run

-> (e -> Pipe a b m r)

handler function

-> Pipe a b m r

Catch an exception within the Pipe monad.

This function takes a Pipe, runs it, and if an exception is raised it executes the handler, passing it the value of the exception. Otherwise, the result is returned as normal.

For example, given a Pipe:

 reader :: Pipe () String IO ()

we can use catch to resume after an exception. For example:

 safeReader :: Pipe () (Either SomeException String) IO ()
 safeReader = catch (reader >+> 'Pipe' Right) $ \e -> do
   yield $ Left e

Note that there is no guarantee that the handler will actually be executed, as any action in a Pipe: Pipes at either side can terminate before the handler has a chance to be executed.

It is therefore common to use ensure within an exception handler to perform cleanup or finalization of resources. However, we recommend using finally or bracket for such use cases.

bracket

Arguments

:: Monad m

=> m r

action to acquire resource

-> (r -> m y)

action to release resource

-> (r -> Pipe a b m x)

Pipe to run in between

-> Pipe a b m x

Allocate a resource within the base monad, run a Pipe, then ensure the resource is released.

The typical example is reading from a file:

 bracket
   (openFile "filename" ReadMode)
   hClose
   (\handle -> do
       line <- lift $ hGetLine handle
       yield line
       ...)

bracket_

Arguments

:: Monad m

=> m r

action to run first

-> m y

action to run last

-> Pipe a b m x

Pipe to run in between

-> Pipe a b m x

A variant of bracket where the return value from the allocation action is not required.

bracketOnError

Arguments

:: Monad m

=> m r

action to acquire resource

-> (r -> m y)

action to release resource

-> (r -> Pipe a b m x)

Pipe to run in between

-> Pipe a b m x

Like bracket, but only performs the "release" action if there was an exception raised by the Pipe.

finally

Arguments

:: Monad m

=> Pipe a b m r

Pipe to run first

-> m s

finalizer action

-> Pipe a b m r

A specialized variant of bracket with just a computation to run afterwards.

onException

Arguments

:: Monad m

=> Pipe a b m r

Pipe to run first

-> Pipe a b m s

Pipe to run if an exception happens

-> Pipe a b m r

Like finally, but only performs the final action if there was an exception raised by the Pipe.