-- 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 MonadBaseControl, a
-- subset of MonadBase into which generic control operations
-- such as catch can be lifted from IO or any other
-- base monad. Instances are based on monad transformers in
-- MonadTransControl, which includes all standard monad
-- transformers in the transformers library except
-- ContT.
--
-- See the lifted-base package which uses monad-control
-- to lift IO operations from the base library (like
-- catch or bracket) into any monad that is an instance
-- of MonadBase or MonadBaseControl.
--
-- 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 and
-- TypeFamilies language extensions to simplify and speedup most
-- definitions.
--
-- The following critertion based benchmark shows that
-- monad-control is on average about 99% faster than
-- monad-peel:
--
--
-- git clone https://github.com/basvandijk/bench-monad-peel-control
--
@package monad-control
@version 0.3
-- | (TODO: It would be nicer if the associated data types
-- StT and StM were associated type synonyms
-- instead. This would simplify a lot of code and could make some
-- definitions more efficient because there'll be no need to wrap the
-- monadic state in a data type. Unfortunately GHC has a bug which
-- prevents this: http://hackage.haskell.org/trac/ghc/ticket/5595.
-- I will switch to associated type synonyms when that bug is fixed.)
module Control.Monad.Trans.Control
class MonadTrans t => MonadTransControl t where { data family StT t :: * -> *; }
liftWith :: (MonadTransControl t, Monad m) => (Run t -> m α) -> t m α
restoreT :: (MonadTransControl t, Monad m) => m (StT t α) -> t m α
-- | A function that runs a transformed monad t n on the monadic
-- state that was captured by liftWith
--
-- A Run t function yields a computation in n that
-- returns the monadic state of t. This state can later be used
-- to restore a t computation using restoreT.
type Run t = forall n β. Monad n => t n β -> n (StT t β)
class MonadBase b m => MonadBaseControl b m | m -> b where { data family StM m :: * -> *; }
liftBaseWith :: MonadBaseControl b m => (RunInBase m b -> b α) -> m α
restoreM :: MonadBaseControl b m => StM m α -> m α
-- | A function that runs a m computation on the monadic state
-- that was captured by liftBaseWith
--
-- A RunInBase m function yields a computation in the base monad
-- of m that returns the monadic state of m. This state
-- can later be used to restore the m computation using
-- restoreM.
type RunInBase m b = forall α. m α -> b (StM m α)
-- | Handy type synonym that composes the monadic states of t and
-- m.
--
-- It can be used to define the StM for new
-- MonadBaseControl instances.
type ComposeSt t m α = StM m (StT t α)
-- | Default defintion for the liftBaseWith method.
--
-- Note that it composes a liftWith of t with a
-- liftBaseWith of m to give a liftBaseWith of
-- t m:
--
--
-- defaultLiftBaseWith stM = \f -> liftWith $ \run ->
-- liftBaseWith $ \runInBase ->
-- f $ liftM stM . runInBase . run
--
defaultLiftBaseWith :: (MonadTransControl t, MonadBaseControl b m) => (forall β. ComposeSt t m β -> StM (t m) β) -> ((RunInBase (t m) b -> b α) -> t m α)
-- | Default definition for the restoreM method.
--
-- Note that: defaultRestoreM unStM = restoreT .
-- restoreM . unStM
defaultRestoreM :: (MonadTransControl t, MonadBaseControl b m) => (StM (t m) α -> ComposeSt t m α) -> (StM (t m) α -> t m α)
-- | An often used composition: control f = liftBaseWith f
-- >>= restoreM
control :: MonadBaseControl b m => (RunInBase m b -> b (StM m α)) -> m α
-- | liftBaseOp is a particular application of liftBaseWith
-- that allows lifting control operations of type:
--
-- ((a -> b c) -> b c) to: (MonadBaseControl b
-- m => (a -> m c) -> m c).
--
-- For example:
--
--
-- liftBaseOp alloca :: MonadBaseControl IO m => (Ptr a -> m c) -> m c
--
liftBaseOp :: MonadBaseControl b m => ((α -> b (StM m β)) -> b (StM m γ)) -> ((α -> m β) -> m γ)
-- | liftBaseOp_ is a particular application of
-- liftBaseWith that allows lifting control operations of type:
--
-- (b a -> b a) to: (MonadBaseControl b m => m
-- a -> m a).
--
-- For example:
--
--
-- liftBaseOp_ mask_ :: MonadBaseControl IO m => m a -> m a
--
liftBaseOp_ :: MonadBaseControl b m => (b (StM m α) -> b (StM m β)) -> (m α -> m β)
-- | liftBaseDiscard is a particular application of
-- liftBaseWith that allows lifting control operations of type:
--
-- (b () -> b a) to: (MonadBaseControl b m => m
-- () -> m a).
--
-- Note that, while the argument computation m () has access to
-- the captured state, all its side-effects in m are discarded.
-- It is run only for its side-effects in the base monad b.
--
-- For example:
--
--
-- liftBaseDiscard forkIO :: MonadBaseControl IO m => m () -> m ThreadId
--
liftBaseDiscard :: MonadBaseControl b m => (b () -> b α) -> (m () -> m α)
instance (Monoid w, MonadBaseControl b m) => MonadBaseControl b (RWST r w s m)
instance (Monoid w, MonadBaseControl b m) => MonadBaseControl b (RWST r w s m)
instance (Monoid w, MonadBaseControl b m) => MonadBaseControl b (WriterT w m)
instance (Monoid w, MonadBaseControl b m) => MonadBaseControl b (WriterT w m)
instance (Error e, MonadBaseControl b m) => MonadBaseControl b (ErrorT e m)
instance MonadBaseControl b m => MonadBaseControl b (StateT s m)
instance MonadBaseControl b m => MonadBaseControl b (StateT s m)
instance MonadBaseControl b m => MonadBaseControl b (ReaderT r m)
instance MonadBaseControl b m => MonadBaseControl b (ListT m)
instance MonadBaseControl b m => MonadBaseControl b (MaybeT m)
instance MonadBaseControl b m => MonadBaseControl b (IdentityT m)
instance MonadBaseControl Identity Identity
instance MonadBaseControl ((->) r) ((->) r)
instance MonadBaseControl [] []
instance MonadBaseControl (Either e) (Either e)
instance MonadBaseControl Maybe Maybe
instance MonadBaseControl STM STM
instance MonadBaseControl (ST s) (ST s)
instance MonadBaseControl (ST s) (ST s)
instance MonadBaseControl IO IO
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 ListT
instance Error e => MonadTransControl (ErrorT e)
instance MonadTransControl MaybeT
instance MonadTransControl IdentityT