-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Lift control operations, like exception catching, through monad transformers
--
-- This package defines the type class MonadControlIO, a subset
-- of MonadIO into which generic control operations such as
-- catch can be lifted from IO. Instances are based on
-- monad transformers in MonadTransControl, which includes all
-- standard monad transformers in the transformers library
-- except ContT. For convenience, it provides a wrapped version
-- of Control.Exception with types generalized from IO
-- to all monads in MonadControlIO.
--
-- Note that this package is a rewrite of Anders Kaseorg's
-- monad-peel library. The main difference is that this package
-- provides CPS style operators and exploits the RankNTypes
-- language extension to simplify most definitions.
--
-- The package includes a copy of the monad-peel testsuite
-- written by Anders Kaseorg. The tests can be performed by using
-- cabal test.
--
-- The following critertion based benchmark shows that
-- monad-control is on average about 2.5 times faster than
-- monad-peel:
--
--
-- http://code.haskell.org/~basvandijk/code/bench-monad-peel-control
@package monad-control
@version 0.2
-- | This module defines the class MonadTransControl of monad
-- transformers through which control operations can be lifted. Instances
-- are included for all the standard monad transformers from the
-- transformers library except ContT.
--
-- idLiftControl and liftLiftControlBase are provided to
-- assist creation of MonadControlIO-like classes (see
-- Control.Monad.IO.Control) based on core monads other than
-- IO.
module Control.Monad.Trans.Control
-- | MonadTransControl is the class of monad transformers
-- supporting an extra operation liftControl, enabling control
-- operations (functions that use monadic actions as input instead of
-- just output) to be lifted through the transformer.
class MonadTrans t => MonadTransControl t
liftControl :: (MonadTransControl t, Monad m) => (Run t -> m a) -> t m a
type Run t = forall n o b. (Monad n, Monad o, Monad (t o)) => t n b -> n (t o b)
-- | An often used composition: control = join .
-- liftControl
control :: (Monad m, Monad (t m), MonadTransControl t) => (Run t -> m (t m a)) -> t m a
-- | idLiftControl acts as the "identity" liftControl
-- operation from a monad m to itself.
--
--
-- idLiftControl f = f $ liftM return
--
--
-- It serves as the base case for a class like MonadControlIO,
-- which allows control operations in some base monad (here IO)
-- to be lifted through arbitrary stacks of zero or more monad
-- transformers in one call. For example, Control.Monad.IO.Control
-- defines:
--
--
-- class MonadIO m => MonadControlIO m where
-- liftControlIO :: (RunInBase m IO -> IO b) -> m b
--
--
--
-- instance MonadControlIO IO where
-- liftControlIO = idLiftControl
--
idLiftControl :: Monad m => (RunInBase m m -> m a) -> m a
type RunInBase m base = forall b. m b -> base (m b)
-- | liftLiftControlBase is used to compose two liftControl
-- operations: the outer provided by a MonadTransControl instance,
-- and the inner provided as the argument.
--
-- It satisfies liftLiftControlBase idLiftControl ==
-- liftControl.
--
-- It serves as the induction step of a MonadControlIO-like
-- class. For example, Control.Monad.IO.Control defines:
--
--
-- instance MonadControlIO m => MonadControlIO (StateT s m) where
-- liftControlIO = liftLiftControlBase liftControlIO
--
--
-- using the MonadTransControl instance of StateT
-- s.
--
-- The following shows the recursive structure of liftControlIO
-- applied to a stack of three monad transformers with IO as the base
-- monad: t1 (t2 (t3 IO)) a:
--
--
-- liftControlIO
-- =
-- liftLiftControlBase $
-- liftLiftControlBase $
-- liftLiftControlBase $
-- idLiftControl
-- =
-- \f -> liftControl $ \run1 -> -- Capture state of t1, run1 :: Run t1
-- liftControl $ \run2 -> -- Capture state of t2, run2 :: Run t2
-- liftControl $ \run3 -> -- Capture state of t3, run3 :: Run t3
-- let run :: RunInBase (t1 (t2 (t3 IO))) IO
-- run = -- Restore state
-- liftM (join . lift) -- :: IO ( t2 (t3 IO) (t1 (t2 (t3 IO)) a)) -> IO ( t1 (t2 (t3 IO)) a)
-- . liftM (join . lift) -- :: IO ( t3 IO (t2 (t3 IO) (t1 (t2 (t3 IO)) a))) -> IO ( t2 (t3 IO) (t1 (t2 (t3 IO)) a))
-- -- Identity conversion
-- . liftM (join . lift) -- :: IO (IO (t3 IO (t2 (t3 IO) (t1 (t2 (t3 IO)) a)))) -> IO ( t3 IO (t2 (t3 IO) (t1 (t2 (t3 IO)) a)))
-- . liftM return -- :: IO ( t3 IO (t2 (t3 IO) (t1 (t2 (t3 IO)) a))) -> IO (IO (t3 IO (t2 (t3 IO) (t1 (t2 (t3 IO)) a))))
-- -- Run (computation to run:) (inner monad:) (restore computation:)
-- . run3 -- :: t3 IO (t2 (t3 IO) (t1 (t2 (t3 IO)) a)) -> IO (t3 IO (t2 (t3 IO) (t1 (t2 (t3 IO)) a)))
-- . run2 -- :: t2 (t3 IO) (t1 (t2 (t3 IO)) a) -> t3 IO (t2 (t3 IO) (t1 (t2 (t3 IO)) a))
-- . run1 -- :: t1 (t2 (t3 IO)) a -> t2 (t3 IO) (t1 (t2 (t3 IO)) a)
-- in f run
--
liftLiftControlBase :: (MonadTransControl t, Monad (t m), Monad m, Monad base) => ((RunInBase m base -> base a) -> m a) -> ((RunInBase (t m) base -> base a) -> t m a)
instance Monoid w => MonadTransControl (RWST r w s)
instance Monoid w => MonadTransControl (RWST r w s)
instance Monoid w => MonadTransControl (WriterT w)
instance Monoid w => MonadTransControl (WriterT w)
instance MonadTransControl (StateT s)
instance MonadTransControl (StateT s)
instance MonadTransControl (ReaderT r)
instance MonadTransControl MaybeT
instance MonadTransControl ListT
instance Error e => MonadTransControl (ErrorT e)
instance MonadTransControl IdentityT
-- | This module defines the class MonadControlIO of IO-based
-- monads into which control operations on IO (such as exception
-- catching; see Control.Exception.Control) can be lifted.
--
-- liftIOOp and liftIOOp_ enable convenient lifting of two
-- common special cases of control operation types.
module Control.Monad.IO.Control
-- | MonadControlIO is the class of IO-based monads
-- supporting an extra operation liftControlIO, enabling control
-- operations on IO to be lifted into the monad.
class MonadIO m => MonadControlIO m
liftControlIO :: MonadControlIO m => (RunInBase m IO -> IO a) -> m a
-- | An often used composition: controlIO = join .
-- liftControlIO
controlIO :: MonadControlIO m => (RunInBase m IO -> IO (m a)) -> m a
-- | liftIOOp is a particular application of liftControlIO
-- that allows lifting control operations of type (a -> IO
-- b) -> IO b (e.g. alloca, withMVar v)
-- to MonadControlIO m => (a -> m b) -> m b.
--
--
-- liftIOOp f = \g -> controlIO $ runInIO -> f $ runInIO . g
--
liftIOOp :: MonadControlIO m => ((a -> IO (m b)) -> IO (m c)) -> (a -> m b) -> m c
-- | liftIOOp_ is a particular application of liftControlIO
-- that allows lifting control operations of type IO a ->
-- IO a (e.g. block) to MonadControlIO m
-- => m a -> m a.
--
--
-- liftIOOp_ f = \m -> controlIO $ runInIO -> f $ runInIO m
--
liftIOOp_ :: MonadControlIO m => (IO (m a) -> IO (m b)) -> m a -> m b
instance (Monoid w, MonadControlIO m) => MonadControlIO (RWST r w s m)
instance (Monoid w, MonadControlIO m) => MonadControlIO (RWST r w s m)
instance (Monoid w, MonadControlIO m) => MonadControlIO (WriterT w m)
instance (Monoid w, MonadControlIO m) => MonadControlIO (WriterT w m)
instance MonadControlIO m => MonadControlIO (StateT s m)
instance MonadControlIO m => MonadControlIO (StateT s m)
instance MonadControlIO m => MonadControlIO (ReaderT r m)
instance (Error e, MonadControlIO m) => MonadControlIO (ErrorT e m)
instance MonadControlIO m => MonadControlIO (MaybeT m)
instance MonadControlIO m => MonadControlIO (ListT m)
instance MonadControlIO m => MonadControlIO (IdentityT m)
instance MonadControlIO IO
-- | This is a wrapped version of Control.Exception with types
-- generalized from IO to all monads in MonadControlIO.
module Control.Exception.Control
-- | Generalized version of throwIO.
throwIO :: (MonadIO m, Exception e) => e -> m a
-- | Generalized version of ioError.
ioError :: MonadIO m => IOError -> m a
-- | Generalized version of catch.
catch :: (MonadControlIO m, Exception e) => m a -> (e -> m a) -> m a
-- | Generalized version of catches.
catches :: MonadControlIO m => m a -> [Handler m a] -> m a
-- | Generalized version of Handler.
data Handler m a
Handler :: (e -> m a) -> Handler m a
-- | Generalized version of catchJust.
catchJust :: (MonadControlIO m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
-- | Generalized version of handle.
handle :: (MonadControlIO m, Exception e) => (e -> m a) -> m a -> m a
-- | Generalized version of handleJust.
handleJust :: (MonadControlIO m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
-- | Generalized version of try.
try :: (MonadControlIO m, Exception e) => m a -> m (Either e a)
-- | Generalized version of tryJust.
tryJust :: (MonadControlIO m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
-- | Generalized version of evaluate.
evaluate :: MonadIO m => a -> m a
-- | Generalized version of mask.
mask :: MonadControlIO m => ((forall a. m a -> m a) -> m b) -> m b
-- | Generalized version of mask_.
mask_ :: MonadControlIO m => m a -> m a
-- | Generalized version of uninterruptibleMask.
uninterruptibleMask :: MonadControlIO m => ((forall a. m a -> m a) -> m b) -> m b
-- | Generalized version of uninterruptibleMask_.
uninterruptibleMask_ :: MonadControlIO m => m a -> m a
-- | Generalized version of getMaskingState.
getMaskingState :: MonadIO m => m MaskingState
-- | Generalized version of blocked. returns True if
-- asynchronous exceptions are blocked in the current thread.
blocked :: MonadIO m => m Bool
-- | Generalized version of bracket. Note, any monadic side effects
-- in m of the "release" computation will be discarded; it is
-- run only for its side effects in IO.
bracket :: MonadControlIO m => m a -> (a -> m b) -> (a -> m c) -> 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.
bracket_ :: MonadControlIO m => m a -> m b -> m c -> m c
-- | Generalized version of bracketOnError. Note, any monadic side
-- effects in m of the "release" computation will be discarded.
bracketOnError :: MonadControlIO m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | Generalized version of finally. Note, any monadic side effects
-- in m of the "afterward" computation will be discarded.
finally :: MonadControlIO 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.
onException :: MonadControlIO m => m a -> m b -> m a