-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Modular type class machinery for monad transformer stacks.
--
-- The layers package provides the type class machinery needed
-- to make monads built out of stacks of monad transformers easy to use.
-- It introduces the concept of monad layers, which are a generalisation
-- of monad transformers. The type class machinery provided by and the
-- design patterns suggested by layers allow for much more
-- modularity than is possible with the existing type class machinery and
-- design patterns. With layers it is possible to use arbitrary
-- monad interfaces (monad interfaces are what we call the sort of type
-- classes that you see in the mtl and similar packages) with
-- arbtirary monad transformers (by monad transformers here, we are
-- specifically to monad constructors, such as the ones defined in
-- transformers), without ever having to explicitly define how
-- to lift specific interfaces through specific transformers.
--
-- layers improves upon and/or replaces, in part or in whole,
-- the following list of packages: transformers, mtl,
-- mmtl, transformers-base, monad-control,
-- lifted-base, monad-peel,
-- MonadCatchIO-transformers, MonadCatchIO-mtl,
-- exception-transformers, monad-abort-fd and probably
-- more too. There have been many attempts to either improve upoin or
-- work around the deficiencies of the existing type class machinery for
-- monad transformer stacks, but we believe layers is the most
-- complete of any of these so far.
--
-- A comprehensive overview of the motivation behind layers and
-- an explanation of the design decisions taken is given in
-- Documentation.Layers.Overview. It is highly recommended
-- that you read this if you are considering using this package. The core
-- type classes of the package are defined in Control.Monad.Layer
-- (this can be thought of as equivalent to or a replacement of
-- Control.Monad.Trans.Class from transformers). The rest
-- of the modules in this package export monad interfaces, in the
-- Control.Monad.Interface hierarchy, including replacements for
-- all of the monad interfaces of the mtl package.
@package layers
@version 0.1
-- | This module is the core of the layers package. It exports:
--
--
-- - The type classes MonadLayer, MonadLayerFunctor and
-- MonadLayerControl and instances of these classes for the
-- transformers in the transformers package.
-- - The type classes MonadTrans, MonadTransFunctor and
-- MonadTransControl and instances of these classes for the
-- transformers in the transformers package.
-- - The type classes MonadLift, MonadLiftFunctor and
-- MonadLiftControl.
-- - Two sets of helper functions inspired by similarly named functions
-- in the monad-control package: one for instances of
-- MonadLayerControl and the other for instances of
-- MonadLiftControl. These operations are: controlLayer,
-- layerOp, layerOp_ and layerDiscard and
-- control, liftOp, liftOp_ and liftDiscard
-- respectively.
--
module Control.Monad.Layer
-- | A monad m can be an instance of MonadLayer if it is
-- built ("layered") on top of some inner monad (Inner m)
-- and can provide the operations layer and layerInvmap.
--
-- Monad layers are a generalisation of monad transformers, with the
-- difference being that monad layers are not necessarily parametric in
-- their inner monad. For more details, read the the in-depth
-- documentation provided in Documentation.Layers.Overview.
class (Monad m, Monad (Inner m)) => MonadLayer m where type family Inner m :: * -> *
layer :: MonadLayer m => Inner m a -> m a
layerInvmap :: MonadLayer m => (forall b. Inner m b -> Inner m b) -> (forall b. Inner m b -> Inner m b) -> m a -> m a
-- | The type class MonadLayerFunctor represents is the subclass of
-- monad layers that support the layerMap operation, which is more
-- powerful than the layerInvmap operation of the
-- MonadLayer type class.
class MonadLayer m => MonadLayerFunctor m
layerMap :: MonadLayerFunctor m => (forall b. Inner m b -> Inner m b) -> m a -> m a
-- | MonadLayerControl represents the class of monad layers through
-- which it is possible to lift control operations. See
-- Documentation.Layers.Overview for a more complete discussion.
class MonadLayerFunctor m => MonadLayerControl m where data family LayerState m :: * -> * zero _ = False
zero :: MonadLayerControl m => LayerState m a -> Bool
restore :: MonadLayerControl m => LayerState m a -> m a
layerControl :: MonadLayerControl m => ((forall b. m b -> Inner m (LayerState m b)) -> Inner m a) -> m a
-- | Monad transformers are a subclass of monad layers which are parametric
-- in their inner monad.
class (MonadLayer m, m ~ Outer m (Inner m)) => MonadTrans m where type family Outer m :: (* -> *) -> * -> *
transInvmap :: (MonadTrans m, MonadTrans n, Outer n ~ Outer m) => (forall b. Inner m b -> Inner n b) -> (forall b. Inner n b -> Inner m b) -> m a -> n a
-- | The type class MonadTransFunctor represents is the subclass of
-- monad layers that support the transMap operation, which is more
-- powerful than the transInvmap operation of the
-- MonadTrans type class.
class (MonadLayerFunctor m, MonadTrans m) => MonadTransFunctor m
transMap :: (MonadTransFunctor m, MonadTrans n, Outer n ~ Outer m) => (forall b. Inner m b -> Inner n b) -> m a -> n a
-- | MonadTransControl is a variant of MonadLayerControl for
-- monad transformers, i.e., monad layers polymorphic in their inner
-- monad. This extra polymorphism allows us to specify more type safety
-- in the run operation of transControl, but in practice
-- there is no reason to ever use this over MonadLayerControl.
-- See Documentation.Layers.Overview for a discussion of why this
-- class is included despite not being strictly necessary.
class (MonadLayerControl m, MonadTransFunctor m) => MonadTransControl m
transControl :: MonadTransControl m => (forall n. (MonadTrans n, Outer n ~ Outer m) => (forall b. n b -> Inner n (LayerState n b)) -> Inner n a) -> m a
-- | MonadLift is a multi-parameter type class parameterised by two
-- monads i and m. If the constraint MonadLift i
-- m is satisfied, this means that m supports lifting
-- operations from i. If m is a monad built from a
-- monad transformer stack, then it supports lifting operations from any
-- monad i anywhere in the stack. We call such a relationship
-- between i and m a "monad lift". For a more details,
-- read the in-depth documentation provided in
-- Documentation.Layers.Overview.
class (Monad i, Monad m) => MonadLift i m
lift :: MonadLift i m => i a -> m a
liftInvmap :: MonadLift i m => (forall b. i b -> i b) -> (forall b. i b -> i b) -> m a -> m a
-- | The type class MonadLiftFunctor represents is the subclass of
-- monad lifts that support the liftMap operation, which is more
-- powerful than the liftInvmap operation of the MonadLift
-- type class.
class MonadLift i m => MonadLiftFunctor i m
liftMap :: MonadLiftFunctor i m => (forall b. i b -> i b) -> m a -> m a
-- | MonadLiftControl represents the class of monad lifts that
-- support lifting control operations. See
-- Documentation.Layers.Overview for a more complete discussion.
class MonadLiftFunctor i m => MonadLiftControl i m
liftControl :: MonadLiftControl i m => ((forall b. m b -> i (m b)) -> i a) -> m a
-- | An often used composition: controlLayer f =
-- layerControl f >>= restore
controlLayer :: MonadLayerControl m => ((forall b. m b -> Inner m (LayerState m b)) -> Inner m (LayerState m a)) -> m a
-- | layerOp is a particular application of layerControl
-- that allows layering control operations of type: (a ->
-- Inner m b) -> Inner m b to
-- MonadLayerControl m => (a -> m b) -> m b.
--
-- For example:
--
--
-- layerOp . withMVar :: (MonadLayerControl m, Inner m ~ IO)
-- => MVar a -> (a -> m b) -> m b
--
layerOp :: MonadLayerControl m => ((a -> Inner m (LayerState m b)) -> Inner m (LayerState m c)) -> (a -> m b) -> m c
-- | layerOp_ is a particular application of layerControl
-- that allows layering control operations of type: Inner m a
-- -> Inner m b to MonadLayerControl m => m
-- a -> m b.
--
-- For example:
--
--
-- layerOp_ mask_ :: (MonadLayerControl m, Inner m ~ IO) => m a -> m a
--
layerOp_ :: MonadLayerControl m => (Inner m (LayerState m a) -> Inner m (LayerState m b)) -> m a -> m b
-- | layerDiscard is a particular application of
-- layerControl that allows layering control operations of type:
-- Inner m () -> Inner m a to
-- MonadLayerControl 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 inner monad
-- Inner m.
--
-- For example:
--
--
-- layerDiscard forkIO :: (MonadLayerControl m, Inner m ~ IO)
-- => m () -> m ThreadId
--
layerDiscard :: MonadLayerControl m => (Inner m () -> Inner m a) -> m () -> m a
-- | An often used composition: control f = join .
-- liftControl f
control :: MonadLiftControl i m => ((forall b. m b -> i (m b)) -> i (m a)) -> m a
-- | liftOp is a particular application of liftControl that
-- allows lifting control operations of type: (a -> i b) -> i
-- b to MonadLiftControl i m => (a -> m b) -> m
-- b.
--
-- For example:
--
--
-- liftOp . withMVar :: MonadLiftControl IO m => MVar a -> (a -> m b) -> m b
--
liftOp :: MonadLiftControl i m => ((a -> i (m b)) -> i (m c)) -> (a -> m b) -> m c
-- | liftOp_ is a particular application of liftControl
-- that allows lifting control operations of type: i a -> i b
-- to MonadLiftControl i m => m a -> m b.
--
-- For example:
--
--
-- liftOp_ mask_ :: MonadLiftControl IO m => m a -> m a
--
liftOp_ :: MonadLiftControl i m => (i (m a) -> i (m b)) -> m a -> m b
-- | liftDiscard is a particular application of liftControl
-- that allows lifting control operations of type: i () -> i
-- a to MonadLiftControl i 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 inner monad i.
--
-- For example:
--
--
-- liftDiscard forkIO :: MonadLiftControl IO m => m () -> m ThreadId
--
liftDiscard :: MonadLiftControl i m => (i () -> i a) -> m () -> m a
instance [overlap ok] (MonadLayerControl m, MonadLiftControl i (Inner m)) => MonadLiftControl i m
instance [overlap ok] Monad m => MonadLiftControl m m
instance [overlap ok] (MonadLayerFunctor m, MonadLiftFunctor i (Inner m)) => MonadLiftFunctor i m
instance [overlap ok] Monad m => MonadLiftFunctor m m
instance [overlap ok] (MonadLayer m, MonadLift i (Inner m)) => MonadLift i m
instance [overlap ok] Monad m => MonadLift m m
instance [overlap ok] (Monad m, Monoid w) => MonadTransControl (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadTransFunctor (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadTrans (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayerControl (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayerFunctor (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayer (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadTransControl (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadTransFunctor (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadTrans (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayerControl (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayerFunctor (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayer (WriterT w m)
instance [overlap ok] Monad m => MonadTransControl (StateT s m)
instance [overlap ok] Monad m => MonadTransFunctor (StateT s m)
instance [overlap ok] Monad m => MonadTrans (StateT s m)
instance [overlap ok] Monad m => MonadLayerControl (StateT s m)
instance [overlap ok] Monad m => MonadLayerFunctor (StateT s m)
instance [overlap ok] Monad m => MonadLayer (StateT s m)
instance [overlap ok] Monad m => MonadTransControl (StateT s m)
instance [overlap ok] Monad m => MonadTransFunctor (StateT s m)
instance [overlap ok] Monad m => MonadTrans (StateT s m)
instance [overlap ok] Monad m => MonadLayerControl (StateT s m)
instance [overlap ok] Monad m => MonadLayerFunctor (StateT s m)
instance [overlap ok] Monad m => MonadLayer (StateT s m)
instance [overlap ok] (Monad m, Monoid w) => MonadTransControl (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadTransFunctor (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadTrans (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayerControl (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayerFunctor (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayer (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadTransFunctor (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadTrans (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadTransControl (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayerControl (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayerFunctor (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadLayer (RWST r w s m)
instance [overlap ok] Monad m => MonadTransControl (ReaderT r m)
instance [overlap ok] Monad m => MonadTransFunctor (ReaderT r m)
instance [overlap ok] Monad m => MonadTrans (ReaderT r m)
instance [overlap ok] Monad m => MonadLayerControl (ReaderT r m)
instance [overlap ok] Monad m => MonadLayerFunctor (ReaderT r m)
instance [overlap ok] Monad m => MonadLayer (ReaderT r m)
instance [overlap ok] Monad m => MonadTransControl (MaybeT m)
instance [overlap ok] Monad m => MonadTransFunctor (MaybeT m)
instance [overlap ok] Monad m => MonadTrans (MaybeT m)
instance [overlap ok] Monad m => MonadLayerControl (MaybeT m)
instance [overlap ok] Monad m => MonadLayerFunctor (MaybeT m)
instance [overlap ok] Monad m => MonadLayer (MaybeT m)
instance [overlap ok] Monad m => MonadTransControl (ListT m)
instance [overlap ok] Monad m => MonadTransFunctor (ListT m)
instance [overlap ok] Monad m => MonadTrans (ListT m)
instance [overlap ok] Monad m => MonadLayerControl (ListT m)
instance [overlap ok] Monad m => MonadLayerFunctor (ListT m)
instance [overlap ok] Monad m => MonadLayer (ListT m)
instance [overlap ok] Monad m => MonadTransControl (IdentityT m)
instance [overlap ok] Monad m => MonadTransFunctor (IdentityT m)
instance [overlap ok] Monad m => MonadTrans (IdentityT m)
instance [overlap ok] Monad m => MonadLayerControl (IdentityT m)
instance [overlap ok] Monad m => MonadLayerFunctor (IdentityT m)
instance [overlap ok] Monad m => MonadLayer (IdentityT m)
instance [overlap ok] (Error e, Monad m) => MonadTransControl (ErrorT e m)
instance [overlap ok] (Error e, Monad m) => MonadTransFunctor (ErrorT e m)
instance [overlap ok] (Error e, Monad m) => MonadTrans (ErrorT e m)
instance [overlap ok] (Error e, Monad m) => MonadLayerControl (ErrorT e m)
instance [overlap ok] (Error e, Monad m) => MonadLayerFunctor (ErrorT e m)
instance [overlap ok] (Error e, Monad m) => MonadLayer (ErrorT e m)
instance [overlap ok] Monad m => MonadTrans (ContT r m)
instance [overlap ok] Monad m => MonadLayer (ContT r m)
-- | This module exports:
--
--
-- - The MonadCont type class and its operation
-- callCC.
-- - An instance of MonadCont for the ContT monad
-- transformer from the transformers package.
-- - A universal pass-through instance of MonadCont for any
-- existing MonadCont wrapped by a
-- MonadLayerControl.
--
module Control.Monad.Interface.Cont
-- | The MonadCont interface represents computations in
-- continuation-passing style (CPS). In continuation-passing style
-- function result is not returned, but instead is passed to another
-- function, received as a parameter (continuation). Computations are
-- built up from sequences of nested continuations, terminated by a final
-- continuation (often id) which produces the final result. Since
-- continuations are functions which represent the future of a
-- computation, manipulation of the continuation functions can achieve
-- complex manipulations of the future of the computation, such as
-- interrupting a computation in the middle, aborting a portion of a
-- computation, restarting a computation, and interleaving execution of
-- computations. The MonadCont interface adapts CPS to the
-- structure of a monad.
--
-- Before using the MonadCont interface, be sure that you have a
-- firm understanding of continuation-passing style and that
-- continuations represent the best solution to your particular design
-- problem. Many algorithms which require continuations in other
-- languages do not require them in Haskell, due to Haskell's lazy
-- semantics. Abuse of the MonadCont interface can produce code
-- that is impossible to understand and maintain.
class Monad m => MonadCont m
callCC :: MonadCont m => ((a -> m b) -> m a) -> m a
instance [overlap ok] (MonadLayerControl m, MonadCont (Inner m)) => MonadCont m
instance [overlap ok] Monad m => MonadCont (ContT r m)
-- | This module exports:
--
--
-- - The MonadException type class and its operations
-- throw and catch.
-- - Instances of MonadException for IO, Either,
-- STM and the ErrorT monad transformer from the
-- transformers package.
-- - An orphan instance of Error for the SomeException
-- type: this is a necessary hack in order to make ErrorT an
-- instance of MonadException.
-- - A universal pass-through instance of MonadException for any
-- existing MonadException wrapped by a
-- MonadLayerControl.
-- - The utility operations catches, catchJust,
-- handle, handleJust, try and tryJust.
--
module Control.Monad.Interface.Exception
-- | The MonadException type class represents the class of monads
-- which can throw and catch exceptions. This includes
-- IO-based monads as well as Either-like monads.
--
-- Minimal complete definition: throw, catch.
class Monad m => MonadException m
throw :: (MonadException m, Exception e) => e -> m a
catch :: (MonadException m, Exception e) => m a -> (e -> m a) -> m a
-- | Sometimes you want to catch two different sorts of exception. You
-- could do something like
--
--
-- f = expr `catch` \(ex :: ArithException) -> handleArith ex
-- `catch` \(ex :: IOException) -> handleIO ex
--
--
-- However, there are a couple of problems with this approach. The first
-- is that having two exception handlers is inefficient. However, the
-- more serious issue is that the second exception handler will catch
-- exceptions in the first, e.g. in the example above, if
-- handleArith throws an IOException then the second
-- exception handler will catch it.
--
-- Instead, we provide a function catches, which would be used
-- thus:
--
--
-- f = expr `catches` [Handler (\ (ex :: ArithException) -> handleArith ex),
-- Handler (\ (ex :: IOException) -> handleIO ex)]
--
catches :: MonadException m => m a -> [Handler m a] -> m a
-- | You need this when using catches.
data Handler m a
Handler :: (e -> m a) -> Handler m a
-- | The function catchJust is like catch, but it takes an
-- extra argument which is an exception predicate, a function
-- which selects which type of exceptions we're interested in.
--
--
-- catchJust (\e -> if isDoesNotExistErrorType (ioeGetErrorType e)
-- then Just ()
-- else Nothing)
-- (readFile f)
-- (\_ -> do
-- hPutStrLn stderr ("No such file: " ++ show f)
-- return "")
--
--
-- Any other exceptions which are not matched by the predicate are
-- re-raised, and may be caught by an enclosing catch,
-- catchJust, etc.
catchJust :: (MonadException m, Exception e) => (e -> Maybe b) -> m a -> (b -> m a) -> m a
-- | A version of catch with the arguments swapped around; useful in
-- situations where the code for the handler is shorter. For example:
--
--
-- do handle (\NonTermination -> exitWith (ExitFailure 1)) $
-- ...
--
handle :: (MonadException m, Exception e) => (e -> m a) -> m a -> m a
-- | A version of catchJust with the arguments swapped around (see
-- handle).
handleJust :: (MonadException m, Exception e) => (e -> Maybe b) -> (b -> m a) -> m a -> m a
-- | Similar to catch, but returns an Either result which is
-- (Right a) if no exception of type e was
-- raised, or (Left ex) if an exception of type
-- e was raised and its value is ex. If any other type
-- of exception is raised than it will be propogated up to the next
-- enclosing exception handler.
--
--
-- try a = catch (Right `liftM` a) (return . Left)
--
try :: (MonadException m, Exception e) => m a -> m (Either e a)
-- | A variant of try that takes an exception predicate to select
-- which exceptions are caught (c.f. catchJust). If the exception
-- does not match the predicate, it is re-thrown.
tryJust :: (MonadException m, Exception e) => (e -> Maybe b) -> m a -> m (Either b a)
-- | The SomeException type is the root of the exception type
-- hierarchy. When an exception of type e is thrown, behind the
-- scenes it is encapsulated in a SomeException.
data SomeException :: *
instance [overlap ok] Error SomeException
instance [overlap ok] (MonadLayerControl m, MonadException (Inner m)) => MonadException m
instance [overlap ok] (MonadException f, MonadException g) => MonadException (Product f g)
instance [overlap ok] (e ~ SomeException, Monad m) => MonadException (ErrorT e m)
instance [overlap ok] MonadException STM
instance [overlap ok] MonadException IO
instance [overlap ok] e ~ SomeException => MonadException (Either e)
-- | This module exports:
--
--
-- - The MonadMask type class and its operations
-- getMaskingState and setMaskingState.
-- - Instances of MonadMask for all the base monads in the
-- base and transformers packages.
-- - A universal pass-through instance of MonadMask for any
-- existing MonadMask wrapped by a MonadLayer.
-- - The utility operations mask, mask_,
-- uninterruptibleMask, uninterruptibleMask_.
--
module Control.Monad.Interface.Mask
-- | The MonadMask type class is for dealing with asynchronous
-- exceptions. It contains the getMaskingState and
-- setMaskingState operations for getting and setting the
-- MaskingState of the current thread. However, you should never
-- need to use these operations: in particular, using
-- setMaskingState can violate some invariants which are assumed
-- internally by this library. The only reason these functions are
-- exposed at all is that they are necessary to implement mask
-- (which is what you should use instead), and unlike mask, their
-- simpler type signature allows us to define a universal pass-through
-- instance of MonadMask through any MonadLayer, while
-- mask would require MonadLayerControl.
--
-- Every monad should be an instance of MonadMask, and we
-- have provided instances for every base monad in the base and
-- transformers packages. getMaskingState and
-- setMaskingState have default definitions that only need to be
-- overridden in the case of IO and monads layered on top of
-- IO (which we have already done), so it costs nothing to add
-- an instance of MonadMask to a monad. (MonadMask is a
-- prerequisite for implementing MonadTry, which provides the
-- bracket family of functions, which is perhaps more interesting
-- than MonadMask on its own.)
--
-- Minimal complete definition: instance head only.
class Monad m => MonadMask m where getMaskingState = return MaskedInterruptible setMaskingState = const id
getMaskingState :: MonadMask m => m MaskingState
setMaskingState :: MonadMask m => MaskingState -> m a -> m a
-- | Executes a computation with asynchronous exceptions masked.
-- That is, any thread which attempts to raise an exception in the
-- current thread with throwTo will be blocked until asynchronous
-- exceptions are unmasked again.
--
-- The argument passed to mask is a function that takes as its
-- argument another function, which can be used to restore the prevailing
-- masking state within the context of the masked computation. For
-- example, a common way to use mask is to protect the acquisition
-- of a resource:
--
--
-- mask $ \restore -> do
-- x <- acquire
-- restore (do_something_with x) `finally` release
--
--
-- This code guarantees that acquire is paired with
-- release, by masking asynchronous exceptions for the critical
-- parts. (Rather than write this code yourself, it would be better to
-- use bracket which abstracts the general pattern).
--
-- Note that the restore action passed to the argument to
-- mask does not necessarily unmask asynchronous exceptions, it
-- just restores the masking state to that of the enclosing context. Thus
-- if asynchronous exceptions are already masked, mask cannot be
-- used to unmask exceptions again. This is so that if you call a library
-- function with exceptions masked, you can be sure that the library call
-- will not be able to unmask exceptions again. If you are writing
-- library code and need to use asynchronous exceptions, the only way is
-- to create a new thread; see forkWithUnmask.
--
-- Asynchronous exceptions may still be received while in the masked
-- state if the masked thread blocks in certain ways; see
-- Control.Exception#interruptible.
--
-- Threads created by fork inherit the masked state from the
-- parent; that is, to start a thread in blocked mode, use mask_ $
-- fork .... This is particularly useful if you need to establish an
-- exception handler in the forked thread before any asynchronous
-- exceptions are received.
mask :: MonadMask m => ((forall a n. MonadMask n => n a -> n a) -> m b) -> m b
-- | Like mask, but does not pass a restore action to the
-- argument.
mask_ :: MonadMask m => m a -> m a
-- | Like mask, but the masked computation is not interruptible (see
-- Control.Exception#interruptible). THIS SHOULD BE USED WITH
-- GREAT CARE, because if a thread executing in
-- uninterruptibleMask blocks for any reason, then the thread (and
-- possibly the program, if this is the main thread) will be unresponsive
-- and unkillable. This function should only be necessary if you need to
-- mask exceptions around an interruptible operation, and you can
-- guarantee that the interruptible operation will only block for a short
-- period of time.
uninterruptibleMask :: MonadMask m => ((forall a n. MonadMask n => n a -> n a) -> m b) -> m b
-- | Like uninterruptibleMask, but does not pass a restore
-- action to the argument.
uninterruptibleMask_ :: MonadMask m => m a -> m a
instance [overlap ok] (MonadLayer m, MonadMask (Inner m)) => MonadMask m
instance [overlap ok] MonadMask IO
instance [overlap ok] MonadMask STM
instance [overlap ok] MonadMask (ST s)
instance [overlap ok] MonadMask (ST s)
instance [overlap ok] MonadMask ((->) r)
instance [overlap ok] MonadMask []
instance [overlap ok] MonadMask (Either e)
instance [overlap ok] MonadMask Maybe
instance [overlap ok] (MonadMask f, MonadMask g) => MonadMask (Product f g)
instance [overlap ok] MonadMask Identity
-- | This module exports:
--
--
-- - The MonadFork type class and its operations fork and
-- forkOn.
-- - An instance of MonadFork for the IO monad.
-- - A universal pass-through instance of MonadFork for any
-- existing MonadFork wrapped by a
-- MonadLayerControl.
-- - The utility operations forkWithUnmask and
-- forkOnWithUnmask.
--
module Control.Monad.Interface.Fork
-- | The MonadFork type class, for monads which support a fork
-- operation.
--
-- An example of a monad which has a MonadFork instance that is not
-- simply a lifted form of forkIO is the ResourceT
-- monad from the resourcet package, which defines an operation
-- resourceForkIO.
class MonadMask m => MonadFork m
fork :: MonadFork m => m () -> m ThreadId
forkOn :: MonadFork m => Int -> m () -> m ThreadId
-- | Like fork, but the child thread is passed a function that can
-- be used to unmask asynchronous exceptions. This function is typically
-- used in the following way
--
--
-- ... mask_ $ forkIOWithUnmask $ \unmask ->
-- catch (unmask ...) handler
--
--
-- so that the exception handler in the child thread is established with
-- asynchronous exceptions masked, meanwhile the main body of the child
-- thread is executed in the unmasked state.
--
-- Note that the unmask function passed to the child thread
-- should only be used in that thread; the behaviour is undefined if it
-- is invoked in a different thread.
forkWithUnmask :: MonadFork m => ((forall a n. MonadMask n => n a -> n a) -> m ()) -> m ThreadId
-- | Like forkWithUnmask, but the child thread is pinned to the
-- given CPU, as with forkOn.
forkOnWithUnmask :: MonadFork m => Int -> ((forall a n. MonadMask n => n a -> n a) -> m ()) -> m ThreadId
instance [overlap ok] (MonadLayerControl m, MonadFork (Inner m)) => MonadFork m
instance [overlap ok] (MonadFork f, MonadFork g) => MonadFork (Product f g)
instance [overlap ok] MonadFork IO
-- | This module exports:
--
--
-- - The MonadMutVar type class and its operations
-- newRef, readRef, writeRef and
-- atomicModifyRef.
-- - Instances of MonadMutVar for IO, STM, strict
-- ST and lazy ST.
-- - A universal pass-through instance of MonadMutVar for any
-- existing MonadMutVar wrapped by a MonadLayer.
-- - The utility operations atomicModifyRef',
-- atomicWriteRef, modifyRef and modifyRef'.
--
module Control.Monad.Interface.MutVar
-- | The type class MonadMutVar represents the class of monads which
-- support mutable variables. The ref parameter is the type of
-- the mutable variable; e.g., for IO, ref is
-- IORef.
--
-- Minimal complete definition: newRef, readRef,
-- writeRef.
class Monad m => MonadMutVar ref m | m -> ref where atomicModifyRef ref f = do { a <- readRef ref; let (a', b) = f a; writeRef ref a'; return b }
newRef :: MonadMutVar ref m => a -> m (ref a)
readRef :: MonadMutVar ref m => ref a -> m a
writeRef :: MonadMutVar ref m => ref a -> a -> m ()
atomicModifyRef :: MonadMutVar ref m => ref a -> (a -> (a, b)) -> m b
-- | Strict version of atomicModifyRef. This forces both the value
-- stored in the mutable variable as well as the value returned.
atomicModifyRef' :: MonadMutVar ref m => ref a -> (a -> (a, b)) -> m b
-- | Variant of writeRef with the "barrier to reordering" property
-- that atomicModifyRef has.
atomicWriteRef :: MonadMutVar ref m => ref a -> a -> m ()
-- | Mutate the contents of a mutable variable.
--
-- Be warned that modifyRef does not apply the function strictly.
-- This means if the program calls modifyRef many times, but
-- seldomly uses the value, thunks will pile up in memory resulting in a
-- space leak. This is a common mistake made when using a mutable varible
-- as a counter. For example, the following will likely produce a stack
-- overflow:
--
--
-- ref <- newRef 0
-- replicateM_ 1000000 $ modifyRef ref (+1)
-- readRef ref >>= print
--
--
-- To avoid this problem, use modifyRef' instead.
modifyRef :: MonadMutVar ref m => ref a -> (a -> a) -> m ()
-- | Strict version of modifyRef.
modifyRef' :: MonadMutVar ref m => ref a -> (a -> a) -> m ()
instance [overlap ok] (MonadLayer m, MonadMutVar ref (Inner m)) => MonadMutVar ref m
instance [overlap ok] (MonadMutVar ref f, MonadMutVar ref g) => MonadMutVar ref (Product f g)
instance [overlap ok] MonadMutVar TVar STM
instance [overlap ok] MonadMutVar (STRef s) (ST s)
instance [overlap ok] MonadMutVar (STRef s) (ST s)
instance [overlap ok] MonadMutVar IORef IO
-- | This module exports:
--
--
-- - The MonadReader type class and its operations
-- reader, ask and local.
-- - An instance of MonadReader for the ->
-- type.
-- - Instances of MonadReader for the relevant monad
-- transformers from the transformers package (ReaderT', lazy
-- RWST and strict RWST).
-- - A universal pass-through instance of MonadReader for any
-- existing MonadReader wrapped by a MonadLayer.
-- - The utility operations asks.
--
module Control.Monad.Interface.Reader
-- | The 'MonadReader interface monad represents computations which can
-- read values from a shared environment, pass values from function to
-- function and execute sub-computations in a modified environment. Using
-- the MonadReader interface for such computations is often
-- clearer and easier than using the MonadState interface.
--
-- Minimal complete definition: local and one of either
-- reader or ask.
class Monad m => MonadReader r m | m -> r where reader f = liftM f ask ask = reader id
reader :: MonadReader r m => (r -> a) -> m a
ask :: MonadReader r m => m r
local :: MonadReader r m => (r -> r) -> m a -> m a
-- | Retrieves a function of the current environment.
asks :: MonadReader r m => (r -> a) -> m a
instance [overlap ok] (MonadLayer m, MonadReader r (Inner m)) => MonadReader r m
instance [overlap ok] (MonadReader r f, MonadReader r g) => MonadReader r (Product f g)
instance [overlap ok] (Monad m, Monoid w) => MonadReader r (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadReader r (RWST r w s m)
instance [overlap ok] Monad m => MonadReader r (ReaderT r m)
instance [overlap ok] MonadReader r ((->) r)
-- | This module exports:
--
--
-- - The MonadState type class and its operations state,
-- get and put.
-- - Instances of MonadState for the relevant monad transformers
-- from the transformers package (lazy StateT, strict
-- StateT, lazy RWST and strict RWST).
-- - A universal pass-through instance of MonadState for any
-- existing MonadState wrapped by a MonadLayer.
-- - The utility operations modify and gets.
--
module Control.Monad.Interface.State
-- | A pure functional language cannot update values in place because it
-- violates referential transparency. A common idiom to simulate such
-- stateful computations is to "thread" a state parameter through a
-- sequence of functions:
--
-- This approach works, but such code can be error-prone, messy and
-- difficult to maintain. The MonadState interface hides the
-- threading of the state parameter inside the binding operation,
-- simultaneously making the code easier to write, easier to read and
-- easier to modify.
--
-- Minimal complete definition: state or both get and
-- put.
class Monad m => MonadState s m | m -> s where state f = do { s <- get; let ~(a, s') = f s; put s'; return a } get = state (\ s -> (s, s)) put s = state (\ _ -> ((), s))
state :: MonadState s m => (s -> (a, s)) -> m a
get :: MonadState s m => m s
put :: MonadState s m => s -> m ()
-- | Monadic state transformer.
--
-- Maps an old state to a new state inside a state monad. The old state
-- is thrown away.
--
--
-- >>> :t modify ((+1) :: Int -> Int)
-- modify (...) :: (MonadState Int a) => a ()
--
--
-- This says that modify (+1) acts over any Monad that is
-- a member of the MonadState class with an Int state.
modify :: MonadState s m => (s -> s) -> m ()
-- | Gets specific component of the state, using a projection function
-- supplied.
gets :: MonadState s m => (s -> a) -> m a
instance [overlap ok] (MonadLayer m, MonadState s (Inner m)) => MonadState s m
instance [overlap ok] (MonadState s f, MonadState s g) => MonadState s (Product f g)
instance [overlap ok] (Monad m, Monoid w) => MonadState s (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadState s (RWST r w s m)
instance [overlap ok] Monad m => MonadState s (StateT s m)
instance [overlap ok] Monad m => MonadState s (StateT s m)
-- | This module exports:
--
--
-- - The MonadWriter type class and its operations
-- writer, tell, listen and pass.
-- - Instances of MonadWriter for the relevant monad
-- transformers from the transformers package (lazy
-- WriterT, strict WriterT, lazy RWST and strict
-- RWST).
-- - A universal pass-through instance of MonadWriter for any
-- existing MonadWriter wrapped by a MonadLayer.
-- - The utility operations listens and censor.
--
module Control.Monad.Interface.Writer
-- | It is often desirable for a computation to generate output "on the
-- side". Logging and tracing are the most common examples in which data
-- is generated during a computation that we want to retain but is not
-- the primary result of the computation.
--
-- Explicitly managing the logging or tracing data can clutter up the
-- code and invite subtle bugs such as missed log entries. The
-- MonadWriter interface provides a cleaner way to manage the
-- output without cluttering the main computation.
--
-- Minimal complete definition: listen, pass and one of
-- either writer or tell.
class (Monad m, Monoid w) => MonadWriter w m | m -> w where writer ~(a, w) = tell w >> return a tell w = writer ((), w)
writer :: MonadWriter w m => (a, w) -> m a
tell :: MonadWriter w m => w -> m ()
listen :: MonadWriter w m => m a -> m (a, w)
pass :: MonadWriter w m => m (a, w -> w) -> m a
-- | listens f m is an action that executes the action
-- m and adds the result of applying f to the output to
-- the value of the computation.
--
--
-- listens f m = liftM (\(~(a, w)) -> (a, f w)) (listen m)
--
listens :: MonadWriter w m => (w -> b) -> m a -> m (a, b)
-- | censor f m is an action that executes the action
-- m and applies the function f to its output, leaving
-- the return value unchanged.
--
--
-- censor f m = pass (liftM (\a -> (a,f)) m)
--
censor :: MonadWriter w m => (w -> w) -> m a -> m a
instance [overlap ok] (MonadLayer m, MonadWriter w (Inner m)) => MonadWriter w m
instance [overlap ok] (MonadWriter w f, MonadWriter w g) => MonadWriter w (Product f g)
instance [overlap ok] (Monad m, Monoid w) => MonadWriter w (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadWriter w (RWST r w s m)
instance [overlap ok] (Monad m, Monoid w) => MonadWriter w (WriterT w m)
instance [overlap ok] (Monad m, Monoid w) => MonadWriter w (WriterT w m)
-- | This module exports:
--
--
-- - The MonadRWS interface.
-- - The Control.Monad.Interface.Reader module.
-- - The Control.Monad.Interface.State module.
-- - The Control.Monad.Interface.Writer module.
--
module Control.Monad.Interface.RWS
-- | The MonadRWS interface is defined as a type synonym (using the
-- ConstraintKinds extension) for the combination of
-- MonadReader, MonadState and MonadWriter.
type MonadRWS r w s m = (MonadReader r m, MonadWriter w m, MonadState s m)
-- | This module exports:
--
--
-- - The MonadTry type class and its operation mtry.
-- - Instances of MonadTry for all the base monads in the
-- base and transformers packages.
-- - A universal pass-through instance of MonadMask for any
-- existing MonadMask wrapped by a
-- MonadLayerControl.
-- - The utility operations bracket, bracket_,
-- bracketOnError, finally and onException.
--
module Control.Monad.Interface.Try
-- | The MonadTry type class provides a single operation
-- mtry, which is a way to observe short-circuiting in monads. The
-- name refers to the fact that mtry is a generalised version of
-- try: whereas try guards against the specific case of a
-- MonadException short-circuiting due to an exception being
-- thrown, it can still short-circuit in other ways: e.g., if a
-- MaybeT IO returns mzero
-- (Nothing). The action returned by mtry is guaranteed to
-- never short-circuit.
--
-- Nearly every monad should have an instance of MonadTry, with
-- the exception of CPS-style monads whose (possible) short-circuiting is
-- impossible to observe. Instances for every base monad in the
-- base and transformers packages. mtry has a
-- default definition that only needs to be overridden for monads which
-- actually short-circuit, so it costs very little to add an instance of
-- MonadTry to a monad.
--
-- Minimal complete definition: instance head only.
class MonadMask m => MonadTry m where mtry = liftM Right
mtry :: MonadTry m => m a -> m (Either (m a) a)
-- | When you want to acquire a resource, do some work with it, and then
-- release the resource, it is a good idea to use bracket, because
-- bracket will install the necessary handler to release the
-- resource in the event that the monad short circuits during the
-- computation. If the monad short-circuits, then bracket will
-- re-return the monad in its short-circuited state (after performing the
-- release).
--
-- A common example is opening a file:
--
--
-- bracket
-- (openFile "filename" ReadMode)
-- (hClose)
-- (\fileHandle -> do { ... })
--
--
-- The arguments to bracket are in this order so that we can
-- partially apply it, e.g.:
--
--
-- withFile name mode = bracket (openFile name mode) hClose
--
bracket :: MonadTry m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | A variant of bracket where the return value from the first
-- computation is not required.
bracket_ :: MonadTry m => m a -> m b -> m c -> m c
-- | Like bracket, but only performs the final action if the monad
-- short-circuited during the in-between computation.
bracketOnError :: MonadTry m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | A specialised variant of bracket with just a computation to run
-- afterward.
finally :: MonadTry m => m a -> m b -> m a
-- | Like finally, but only performs the final action if the monad
-- short-circuited during the computation.
onException :: MonadTry m => m a -> m b -> m a
instance [overlap ok] (MonadLayerControl m, MonadTry (Inner m)) => MonadTry m
instance [overlap ok] MonadTry STM
instance [overlap ok] MonadTry (ST s)
instance [overlap ok] MonadTry (ST s)
instance [overlap ok] MonadTry IO
instance [overlap ok] MonadTry ((->) r)
instance [overlap ok] MonadTry []
instance [overlap ok] MonadTry (Either e)
instance [overlap ok] MonadTry Maybe
instance [overlap ok] (MonadTry f, MonadTry g) => MonadTry (Product f g)
instance [overlap ok] MonadTry Identity
-- | This document discusses extensively the motivation behind the
-- layers package and explains the design decisions taken in its
-- construction.
-- | Warning: This module exports no types, functions, classes or
-- instances. It exists solely for the Haddock documentation it produces.
-- You should not ever need to import it.
module Documentation.Layers.Overview