unexceptionalio-0.5.1: IO without any non-error, synchronous exceptions

Safe Haskell | Safe-Inferred
Language | Haskell2010

UnexceptionalIO

Contents

- Unsafe entry points
- Pseudo exceptions
- Pseudo exception helpers

Description

When you've caught all the exceptions that can be handled safely, this is what you're left with.

    runEitherIO . fromIO ≡ id

It is intended that you use qualified imports with this library.

    import UnexceptionalIO (UIO)
    import qualified UnexceptionalIO as UIO

Synopsis

- data UIO a
- class Monad m => Unexceptional (m :: Type -> Type) where
  - lift :: UIO a -> m a
- fromIO :: Unexceptional m => IO a -> m (Either SomeNonPseudoException a)
- fromIO' :: (Exception e, Unexceptional m) => (SomeNonPseudoException -> e) -> IO a -> m (Either e a)
- run :: UIO a -> IO a
- runEitherIO :: Exception e => UIO (Either e a) -> IO a
- unsafeFromIO :: Unexceptional m => IO a -> m a
- data SomeNonPseudoException
- data PseudoException
  - = ProgrammerError ProgrammerError
  - | ExternalError ExternalError
  - | Exit ExitCode
- data ProgrammerError
  - = TypeError TypeError
  - | ArithException ArithException
  - | ArrayException ArrayException
  - | AssertionFailed AssertionFailed
  - | ErrorCall ErrorCall
  - | NestedAtomically NestedAtomically
  - | NoMethodError NoMethodError
  - | PatternMatchFail PatternMatchFail
  - | RecConError RecConError
  - | RecSelError RecSelError
  - | RecUpdError RecSelError
- data ExternalError
  - = CompactionFailed CompactionFailed
  - | FixIOException FixIOException
  - | AsyncException SomeAsyncException
  - | BlockedIndefinitelyOnSTM BlockedIndefinitelyOnSTM
  - | BlockedIndefinitelyOnMVar BlockedIndefinitelyOnMVar
  - | Deadlock Deadlock
  - | NonTermination NonTermination
- bracket :: Unexceptional m => UIO a -> (a -> UIO ()) -> (a -> UIO c) -> m c
- forkFinally :: Unexceptional m => UIO a -> (Either PseudoException a -> UIO ()) -> m ThreadId
- fork :: Unexceptional m => UIO () -> m ThreadId
- newtype ChildThreadError = ChildThreadError PseudoException

# Documentation

data UIO a Source #

Like IO, but throws only `PseudoException`

#### Instances

Instances details

Applicative UIO Source # |
Instance details Defined in UnexceptionalIO Methods pure :: a -> UIO a Source # (<*>) :: UIO (a -> b) -> UIO a -> UIO b Source # liftA2 :: (a -> b -> c) -> UIO a -> UIO b -> UIO c Source # (*>) :: UIO a -> UIO b -> UIO b Source # (<*) :: UIO a -> UIO b -> UIO a Source #
Functor UIO Source # |
Instance details Defined in UnexceptionalIO Methods fmap :: (a -> b) -> UIO a -> UIO b Source # (<$) :: a -> UIO b -> UIO a Source #
Monad UIO Source # |
Instance details Defined in UnexceptionalIO Methods (>>=) :: UIO a -> (a -> UIO b) -> UIO b Source # (>>) :: UIO a -> UIO b -> UIO b Source # return :: a -> UIO a Source #
MonadFix UIO Source # |
Instance details Defined in UnexceptionalIO Methods mfix :: (a -> UIO a) -> UIO a Source #
Unexceptional UIO Source # |
Instance details Defined in UnexceptionalIO Methods lift :: UIO a -> UIO a Source #

class Monad m => Unexceptional (m :: Type -> Type) where Source #

Monads in which `UIO` computations may be embedded

Methods

lift :: UIO a -> m a Source #

#### Instances

Instances details

Unexceptional IO Source # |
Instance details Defined in UnexceptionalIO Methods lift :: UIO a -> IO a Source #
Unexceptional UIO Source # |
Instance details Defined in UnexceptionalIO Methods lift :: UIO a -> UIO a Source #

fromIO :: Unexceptional m => IO a -> m (Either SomeNonPseudoException a) Source #

Catch any exception but `PseudoException` in an `IO` action

fromIO' Source #

Arguments

:: (Exception e, Unexceptional m) |
=> (SomeNonPseudoException -> e) | Default if an unexpected exception occurs
-> IO a |
-> m (Either e a) |

Catch any `e` in an `IO` action, with a default mapping for unexpected cases

run :: UIO a -> IO a Source #

Re-embed `UIO` into `IO`

runEitherIO :: Exception e => UIO (Either e a) -> IO a Source #

Re-embed `UIO` and possible exception back into `IO`

# Unsafe entry points

unsafeFromIO :: Unexceptional m => IO a -> m a Source #

You promise there are no exceptions but `PseudoException` thrown by this `IO` action

# Pseudo exceptions

data SomeNonPseudoException Source #

Every `SomeException` but `PseudoException`

#### Instances

Instances details

Exception SomeNonPseudoException Source # |
Instance details Defined in UnexceptionalIO Methods toException :: SomeNonPseudoException -> SomeException Source # fromException :: SomeException -> Maybe SomeNonPseudoException Source # displayException :: SomeNonPseudoException -> String Source # backtraceDesired :: SomeNonPseudoException -> Bool Source #
Show SomeNonPseudoException Source # |
Instance details Defined in UnexceptionalIO Methods showsPrec :: Int -> SomeNonPseudoException -> ShowS Source # show :: SomeNonPseudoException -> String Source # showList :: [SomeNonPseudoException] -> ShowS Source #

data PseudoException Source #

Not everything handled by the exception system is a run-time error you can handle. This is the class of unrecoverable pseudo-exceptions.

Additionally, except for `ExitCode` any of these pseudo-exceptions you could never guarantee to have caught. Since they can come from anywhere at any time, we could never guarentee that `UIO` does not contain them.

Constructors

ProgrammerError ProgrammerError | Mistakes programmers make
ExternalError ExternalError | Errors thrown by the runtime
Exit ExitCode | Process exit requests

#### Instances

Instances details

Exception PseudoException Source # |
Instance details Defined in UnexceptionalIO Methods toException :: PseudoException -> SomeException Source # fromException :: SomeException -> Maybe PseudoException Source # displayException :: PseudoException -> String Source # backtraceDesired :: PseudoException -> Bool Source #
Show PseudoException Source # |
Instance details Defined in UnexceptionalIO Methods showsPrec :: Int -> PseudoException -> ShowS Source # show :: PseudoException -> String Source # showList :: [PseudoException] -> ShowS Source #

data ProgrammerError Source #

Pseudo-exceptions caused by a programming error

Partial functions, `error`, `undefined`, etc

Constructors

TypeError TypeError |
ArithException ArithException |
ArrayException ArrayException |
AssertionFailed AssertionFailed |
ErrorCall ErrorCall |
NestedAtomically NestedAtomically |
NoMethodError NoMethodError |
PatternMatchFail PatternMatchFail |
RecConError RecConError |
RecSelError RecSelError |
RecUpdError RecSelError |

#### Instances

Instances details

Exception ProgrammerError Source # |
Instance details Defined in UnexceptionalIO Methods toException :: ProgrammerError -> SomeException Source # fromException :: SomeException -> Maybe ProgrammerError Source # displayException :: ProgrammerError -> String Source # backtraceDesired :: ProgrammerError -> Bool Source #
Show ProgrammerError Source # |
Instance details Defined in UnexceptionalIO Methods showsPrec :: Int -> ProgrammerError -> ShowS Source # show :: ProgrammerError -> String Source # showList :: [ProgrammerError] -> ShowS Source #

data ExternalError Source #

Pseudo-exceptions thrown by the runtime environment

Constructors

CompactionFailed CompactionFailed |
FixIOException FixIOException |
AsyncException SomeAsyncException |
BlockedIndefinitelyOnSTM BlockedIndefinitelyOnSTM |
BlockedIndefinitelyOnMVar BlockedIndefinitelyOnMVar |
Deadlock Deadlock |
NonTermination NonTermination |

#### Instances

Instances details

Exception ExternalError Source # |
Instance details Defined in UnexceptionalIO Methods toException :: ExternalError -> SomeException Source # fromException :: SomeException -> Maybe ExternalError Source # displayException :: ExternalError -> String Source # backtraceDesired :: ExternalError -> Bool Source #
Show ExternalError Source # |
Instance details Defined in UnexceptionalIO Methods showsPrec :: Int -> ExternalError -> ShowS Source # show :: ExternalError -> String Source # showList :: [ExternalError] -> ShowS Source #

# Pseudo exception helpers

bracket :: Unexceptional m => UIO a -> (a -> UIO ()) -> (a -> UIO c) -> m c Source #

When you're doing resource handling, `PseudoException` matters. You still need to use the `bracket` pattern to handle cleanup.

forkFinally :: Unexceptional m => UIO a -> (Either PseudoException a -> UIO ()) -> m ThreadId Source #

Mirrors `forkFinally`, but since the body is `UIO`, the thread must terminate successfully or because of `PseudoException`

fork :: Unexceptional m => UIO () -> m ThreadId Source #

Mirrors `forkIO`, but re-throws errors to the parent thread

- Ignores manual thread kills, since those are on purpose.
- Re-throws async exceptions (`SomeAsyncException`) as is.
- Re-throws `ExitCode` as is in an attempt to exit with the requested code.
- Wraps synchronous `PseudoException` in async `ChildThreadError`.

newtype ChildThreadError Source #

Async signal that a child thread ended due to non-async PseudoException

Constructors

ChildThreadError PseudoException |

#### Instances

Instances details

Exception ChildThreadError Source # |
Instance details Defined in UnexceptionalIO Methods toException :: ChildThreadError -> SomeException Source # fromException :: SomeException -> Maybe ChildThreadError Source # displayException :: ChildThreadError -> String Source # backtraceDesired :: ChildThreadError -> Bool Source #
Show ChildThreadError Source # |
Instance details Defined in UnexceptionalIO Methods showsPrec :: Int -> ChildThreadError -> ShowS Source # show :: ChildThreadError -> String Source # showList :: [ChildThreadError] -> ShowS Source #