Control.Exception.Lifted

lifted-base-0.2.3.6: lifted IO operations from the base library

Copyright | Bas van Dijk, Anders Kaseorg
License | BSD-style
Maintainer | Bas van Dijk <v.dijk.bas@gmail.com>
Stability | experimental
Portability | non-portable (extended exceptions)
Safe Haskell | Trustworthy
Language | Haskell98

Control.Exception.Lifted

Contents

- Throwing exceptions
- Catching exceptions
  - The `catch` functions
  - The `handle` functions
  - The `try` functions
  - The `evaluate` function
- Asynchronous Exceptions
  - Asynchronous exception control
- Brackets
- Utilities

Description

This is a wrapped version of Control.Exception with types generalized from `IO` to all monads in either `MonadBase` or `MonadBaseControl`.

Synopsis

- module Control.Exception
- throwIO :: (MonadBase IO m, Exception e) => e -> m a
- ioError :: MonadBase IO m => IOError -> m a
- throwTo :: (MonadBase IO m, Exception e) => ThreadId -> e -> m ()
- catch :: (MonadBaseControl IO m, Exception e) => m a -> (e -> m a) -> m a
- catches :: MonadBaseControl IO m => m a -> [Handler m a] -> m a
- data Handler m a = forall e . Exception e => Handler (e -> m a)
- catchJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
- handle :: (MonadBaseControl IO m, Exception e) => (e -> m a) -> m a -> m a
- handleJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
- try :: (MonadBaseControl IO m, Exception e) => m a -> m (Either e a)
- tryJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
- evaluate :: MonadBase IO m => a -> m a
- mask :: MonadBaseControl IO m => ((forall a. m a -> m a) -> m b) -> m b
- mask_ :: MonadBaseControl IO m => m a -> m a
- uninterruptibleMask :: MonadBaseControl IO m => ((forall a. m a -> m a) -> m b) -> m b
- uninterruptibleMask_ :: MonadBaseControl IO m => m a -> m a
- getMaskingState :: MonadBase IO m => m MaskingState
- allowInterrupt :: MonadBase IO m => m ()
- bracket :: MonadBaseControl IO m => m a -> (a -> m b) -> (a -> m c) -> m c
- bracket_ :: MonadBaseControl IO m => m a -> m b -> m c -> m c
- bracketOnError :: MonadBaseControl IO m => m a -> (a -> m b) -> (a -> m c) -> m c
- finally :: MonadBaseControl IO m => m a -> m b -> m a
- onException :: MonadBaseControl IO m => m a -> m b -> m a

# Documentation

module Control.Exception

# Throwing exceptions

throwIO :: (MonadBase IO m, Exception e) => e -> m a

Generalized version of `throwIO`.

ioError :: MonadBase IO m => IOError -> m a

Generalized version of `ioError`.

throwTo :: (MonadBase IO m, Exception e) => ThreadId -> e -> m ()

Generalized version of `throwTo`.

# Catching exceptions

## The `catch` functions

catch

Arguments

:: (MonadBaseControl IO m, Exception e) |
=> m a | The computation to run
-> (e -> m a) | Handler to invoke if an exception is raised
-> m a |

Generalized version of `catch`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

catches :: MonadBaseControl IO m => m a -> [Handler m a] -> m a

Generalized version of `catches`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

data Handler m a

Generalized version of `Handler`.

Constructors

forall e . Exception e => Handler (e -> m a) |

catchJust

Arguments

:: (MonadBaseControl IO m, Exception e) |
=> (e -> Maybe b) | Predicate to select exceptions
-> m a | Computation to run
-> (b -> m a) | Handler
-> m a |

Generalized version of `catchJust`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

## The `handle` functions

handle :: (MonadBaseControl IO m, Exception e) => (e -> m a) -> m a -> m a

Generalized version of `handle`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

handleJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a

Generalized version of `handleJust`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

## The `try` functions

try :: (MonadBaseControl IO m, Exception e) => m a -> m (Either e a)

Generalized version of `try`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

tryJust :: (MonadBaseControl IO m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)

Generalized version of `tryJust`.

Note, when the given computation throws an exception any monadic side effects in `m` will be discarded.

## The `evaluate` function

evaluate :: MonadBase IO m => a -> m a

Generalized version of `evaluate`.

# Asynchronous Exceptions

## Asynchronous exception control

The following functions allow a thread to control delivery of asynchronous exceptions during a critical region.

mask :: MonadBaseControl IO m => ((forall a. m a -> m a) -> m b) -> m b

Generalized version of `mask`.

mask_ :: MonadBaseControl IO m => m a -> m a

Generalized version of `mask_`.

uninterruptibleMask :: MonadBaseControl IO m => ((forall a. m a -> m a) -> m b) -> m b

Generalized version of `uninterruptibleMask`.

uninterruptibleMask_ :: MonadBaseControl IO m => m a -> m a

Generalized version of `uninterruptibleMask_`.

getMaskingState :: MonadBase IO m => m MaskingState

Generalized version of `getMaskingState`.

allowInterrupt :: MonadBase IO m => m ()

Generalized version of `allowInterrupt`.

# Brackets

bracket

Arguments

:: MonadBaseControl IO m |
=> m a | computation to run first ("acquire resource")
-> (a -> m b) | computation to run last ("release resource")
-> (a -> m c) | computation to run in-between
-> m c |

Generalized version of `bracket`.

Note:

- When the "acquire" or "release" computations throw exceptions any monadic side effects in `m` will be discarded.
- When the "in-between" computation throws an exception any monadic side effects in `m` produced by that computation will be discarded but the side effects of the "acquire" or "release" computations will be retained.
- Also, any monadic side effects in `m` of the "release" computation will be discarded; it is run only for its side effects in `IO`.

Note that when your `acquire` and `release` computations are of type `IO` it will be more efficient to write:

    liftBaseOp (bracket acquire release)

bracket_

Arguments

:: MonadBaseControl IO m |
=> m a | computation to run first ("acquire resource")
-> m b | computation to run last ("release resource")
-> m c | computation to run in-between
-> m c |

Generalized version of `bracket_`.

Note any monadic side effects in `m` of both the "acquire" and "release" computations will be discarded. To keep the monadic side effects of the "acquire" computation, use `bracket` with constant functions instead.

Note that when your `acquire` and `release` computations are of type `IO` it will be more efficient to write:

    liftBaseOp_ (bracket_ acquire release)

bracketOnError

Arguments

:: MonadBaseControl IO m |
=> m a | computation to run first ("acquire resource")
-> (a -> m b) | computation to run last ("release resource")
-> (a -> m c) | computation to run in-between
-> m c |

Generalized version of `bracketOnError`.

Note:

- When the "acquire" or "release" computations throw exceptions any monadic side effects in `m` will be discarded.
- When the "in-between" computation throws an exception any monadic side effects in `m` produced by that computation will be discarded but the side effects of the "acquire" computation will be retained.
- Also, any monadic side effects in `m` of the "release" computation will be discarded; it is run only for its side effects in `IO`.

Note that when your `acquire` and `release` computations are of type `IO` it will be more efficient to write:

    liftBaseOp (bracketOnError acquire release)

# Utilities

finally

Arguments

:: MonadBaseControl IO m |
=> m a | computation to run first
-> m b | computation to run afterward (even if an exception was raised)
-> m a |

Generalized version of `finally`.

Note, any monadic side effects in `m` of the "afterward" computation will be discarded.

onException :: MonadBaseControl IO m => m a -> m b -> m a

Generalized version of `onException`.

Note, any monadic side effects in `m` of the "afterward" computation will be discarded.