Control.Monad.With

This module defines interfaces for safe resource usage on top of GeneralAllocate, where resource cleanup happens at the end of a lexical scope.

For contexts where nested scope-based allocation and release is insufficient, see Control.Monad.Allocate.

Documentation

class Monad m => MonadWith m where

A monad allowing for exception-safe resource usage within a lexical scope.

The guarantees of MonadWith are weaker than MonadMask: in some monads, it's possible for resources not to get cleaned up if the entire monadic computation is going to be aborted (e.g. an async exception sent to a thread executing a monad with no exception catching). Of course, MonadMask itself can't guarantee cleanup in the presence of SIGKILL... In any case, this allows for MonadWith to be implemented lawfully in more monads (see WithNoContinuation). In particular, the MonadWith instances for IO, ST, and Identity allow for writing monad-generic exception-safe code which can be properly instantiated in IO or mocked out in ST/Identity without changing the code.

Associated Types

type WithException m

Data characterizing exceptional exit from the scope.

type WithException m = SomeException

Methods

stateThreadingGeneralWith

Arguments

:: GeneralAllocate m (WithException m) releaseReturn b a

Allocate the resource

-> (a -> m b)

Use the resource

-> m (b, releaseReturn)

Allocate, use, and release a resource in some scope, threading through some state.

If resource acquisition succeeds, the resource is guaranteed to be released if the monadic computation itself is going to continue. This is weaker than the guarantees of generalBracket, which can't be implemented in monads without exception catching.

See generalWith for the common use case where state threading isn't needed.

Instances

MonadWith Identity

Defined in Control.Monad.With

Associated Types

type WithException Identity

Methods

stateThreadingGeneralWith :: GeneralAllocate Identity (WithException Identity) releaseReturn b a -> (a -> Identity b) -> Identity (b, releaseReturn)

MonadWith IO

Defined in Control.Monad.With

Associated Types

type WithException IO

Methods

stateThreadingGeneralWith :: GeneralAllocate IO (WithException IO) releaseReturn b a -> (a -> IO b) -> IO (b, releaseReturn)

MonadWith (Either e)

Defined in Control.Monad.With

Associated Types

type WithException (Either e)

Methods

stateThreadingGeneralWith :: GeneralAllocate (Either e) (WithException (Either e)) releaseReturn b a -> (a -> Either e b) -> Either e (b, releaseReturn)

MonadWith (ST s)

Defined in Control.Monad.With

Associated Types

type WithException (ST s)

Methods

stateThreadingGeneralWith :: GeneralAllocate (ST s) (WithException (ST s)) releaseReturn b a -> (a -> ST s b) -> ST s (b, releaseReturn)

Monad m => MonadWith (WithNoContinuation m)

Defined in Control.Monad.With

Associated Types

type WithException (WithNoContinuation m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (WithNoContinuation m) (WithException (WithNoContinuation m)) releaseReturn b a -> (a -> WithNoContinuation m b) -> WithNoContinuation m (b, releaseReturn)

MonadWith m => MonadWith (ResourceT m)

Defined in Control.Monad.With

Associated Types

type WithException (ResourceT m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (ResourceT m) (WithException (ResourceT m)) releaseReturn b a -> (a -> ResourceT m b) -> ResourceT m (b, releaseReturn)

MonadWith m => MonadWith (MaybeT m)

Defined in Control.Monad.With

Associated Types

type WithException (MaybeT m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (MaybeT m) (WithException (MaybeT m)) releaseReturn b a -> (a -> MaybeT m b) -> MaybeT m (b, releaseReturn)

MonadWith m => MonadWith (ExceptT e m)

Defined in Control.Monad.With

Associated Types

type WithException (ExceptT e m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (ExceptT e m) (WithException (ExceptT e m)) releaseReturn b a -> (a -> ExceptT e m b) -> ExceptT e m (b, releaseReturn)

MonadWith m => MonadWith (IdentityT m)

Defined in Control.Monad.With

Associated Types

type WithException (IdentityT m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (IdentityT m) (WithException (IdentityT m)) releaseReturn b a -> (a -> IdentityT m b) -> IdentityT m (b, releaseReturn)

MonadWith m => MonadWith (ReaderT r m)

Defined in Control.Monad.With

Associated Types

type WithException (ReaderT r m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (ReaderT r m) (WithException (ReaderT r m)) releaseReturn b a -> (a -> ReaderT r m b) -> ReaderT r m (b, releaseReturn)

MonadWith m => MonadWith (StateT s m)

Defined in Control.Monad.With

Associated Types

type WithException (StateT s m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (StateT s m) (WithException (StateT s m)) releaseReturn b a -> (a -> StateT s m b) -> StateT s m (b, releaseReturn)

MonadWith m => MonadWith (StateT s m)

Defined in Control.Monad.With

Associated Types

type WithException (StateT s m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (StateT s m) (WithException (StateT s m)) releaseReturn b a -> (a -> StateT s m b) -> StateT s m (b, releaseReturn)

(MonadWith m, Monoid w) => MonadWith (WriterT w m)

Defined in Control.Monad.With

Associated Types

type WithException (WriterT w m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (WriterT w m) (WithException (WriterT w m)) releaseReturn b a -> (a -> WriterT w m b) -> WriterT w m (b, releaseReturn)

(MonadWith m, Monoid w) => MonadWith (WriterT w m)

Defined in Control.Monad.With

Associated Types

type WithException (WriterT w m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (WriterT w m) (WithException (WriterT w m)) releaseReturn b a -> (a -> WriterT w m b) -> WriterT w m (b, releaseReturn)

(MonadWith m, Monoid w) => MonadWith (RWST r w s m)

Defined in Control.Monad.With

Associated Types

type WithException (RWST r w s m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (RWST r w s m) (WithException (RWST r w s m)) releaseReturn b a -> (a -> RWST r w s m b) -> RWST r w s m (b, releaseReturn)

(MonadWith m, Monoid w) => MonadWith (RWST r w s m)

Defined in Control.Monad.With

Associated Types

type WithException (RWST r w s m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (RWST r w s m) (WithException (RWST r w s m)) releaseReturn b a -> (a -> RWST r w s m b) -> RWST r w s m (b, releaseReturn)

type With m = GeneralAllocate m (WithException m) ()

Describe the allocation and release of a resource.

A specialization of GeneralAllocate for the most common case with MonadWith, see generalWith.

generalWith

Arguments

:: MonadWith m

=> With m b a

Allocate the resource

-> (a -> m b)

Use the resource

-> m b

Allocate, use, and release a resource in some scope.

If resource acquisition succeeds, the resource is guaranteed to be released if the monadic computation itself is going to continue. This is weaker than the guarantees of generalBracket, which can't be implemented in monads without exception catching.

onFailure

Arguments

:: MonadWith m

=> m a

Main action

-> (WithException m -> m b)

Failure action

-> m a

Run some action if the first action fails.

Exception propagation will continue after the failure action runs.

If failure occurs, the failure action is guaranteed to run if the monadic compuation itself is going to continue. This is weaker than the guranatess of onError, which can't be implemented in monads without exception catching.

generalFinally

Arguments

:: MonadWith m

=> m a

Main action

-> m b

Final action

-> m (a, b)

Run some action after another one completes in an exception-safe manner.

The final action is guaranteed to run if the monadic compuation itself is going to continue. This is weaker than the guranatess of finally, which can't be implemented in monads without exception catching.

class (MonadWith m, Exceptable (WithException m)) => MonadWithExceptable m

A MonadWith whose exception type can be projected into the Haskell exception hierarchy

Instances

(MonadWith m, Exceptable (WithException m)) => MonadWithExceptable m

Defined in Control.Monad.With

newtype WithNoContinuation m a

A helper for DerivingVia a MonadWith and MonadWithExceptable instance for any Monad.

Note that the derived instance is only valid if the monad satisfies the "no continuation" condition, i.e. that if execution of a computation exits a given lexical scope we are guaranteed that either all of the actions within that scope have executed or the entire monadic computation has been terminated.

The most common factors violating "no continuation" are call/cc and exception catching. A monad which allows exception throwing but not catching is not thereby disqualified, as any thrown exception will of necessity propagate until it terminates the entire monadic computation.

Constructors

WithNoContinuation (m a)

Instances

Applicative m => Applicative (WithNoContinuation m)

Defined in Control.Monad.With

Methods

pure :: a -> WithNoContinuation m a

(<*>) :: WithNoContinuation m (a -> b) -> WithNoContinuation m a -> WithNoContinuation m b

liftA2 :: (a -> b -> c) -> WithNoContinuation m a -> WithNoContinuation m b -> WithNoContinuation m c

(*>) :: WithNoContinuation m a -> WithNoContinuation m b -> WithNoContinuation m b

(<*) :: WithNoContinuation m a -> WithNoContinuation m b -> WithNoContinuation m a

Functor m => Functor (WithNoContinuation m)

Defined in Control.Monad.With

Methods

fmap :: (a -> b) -> WithNoContinuation m a -> WithNoContinuation m b

(<$) :: a -> WithNoContinuation m b -> WithNoContinuation m a

Monad m => Monad (WithNoContinuation m)

Defined in Control.Monad.With

Methods

(>>=) :: WithNoContinuation m a -> (a -> WithNoContinuation m b) -> WithNoContinuation m b

(>>) :: WithNoContinuation m a -> WithNoContinuation m b -> WithNoContinuation m b

return :: a -> WithNoContinuation m a

Monad m => MonadWith (WithNoContinuation m)

Defined in Control.Monad.With

Associated Types

type WithException (WithNoContinuation m)

Methods

stateThreadingGeneralWith :: GeneralAllocate (WithNoContinuation m) (WithException (WithNoContinuation m)) releaseReturn b a -> (a -> WithNoContinuation m b) -> WithNoContinuation m (b, releaseReturn)

type WithException (WithNoContinuation m)

Defined in Control.Monad.With

type WithException (WithNoContinuation m) = Void