-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Parallel execution of monadic computations
--   
--   This package defines classes of monads that can perform multiple
--   executions in parallel and combine their results. For any monad that's
--   an instance of the class, the package re-implements a subset of the
--   Control.Monad interface, but with parallel execution.
@package monad-parallel
@version 0.7.2.2


-- | This module defines classes of monads that can perform multiple
--   computations in parallel and, more importantly, combine the results of
--   those parallel computations.
--   
--   There are two classes exported by this module, <a>MonadParallel</a>
--   and <a>MonadFork</a>. The former is more generic, but the latter is
--   easier to use: when invoking any expensive computation that could be
--   performed in parallel, simply wrap the call in <a>forkExec</a>. The
--   function immediately returns a handle to the running computation. The
--   handle can be used to obtain the result of the computation when
--   needed:
--   
--   <pre>
--   do child &lt;- forkExec expensive
--      otherStuff
--      result &lt;- child
--   </pre>
--   
--   In this example, the computations <i>expensive</i> and
--   <i>otherStuff</i> would be performed in parallel. When using the
--   <a>MonadParallel</a> class, both parallel computations must be
--   specified at once:
--   
--   <pre>
--   bindM2 (\ childResult otherResult -&gt; ...) expensive otherStuff
--   </pre>
--   
--   In either case, for best results the costs of the two computations
--   should be roughly equal.
--   
--   Any monad that is an instance of the <a>MonadFork</a> class is also an
--   instance of the <a>MonadParallel</a> class, and the following law
--   should hold:
--   
--   <pre>
--   bindM2 f ma mb = do {a' &lt;- forkExec ma; b &lt;- mb; a &lt;- a'; f a b}
--   </pre>
--   
--   When operating with monads free of side-effects, such as
--   <a>Identity</a> or <a>Maybe</a>, <a>forkExec</a> is equivalent to
--   <a>return</a> and <a>bindM2</a> is equivalent to <tt> \ f ma mb -&gt;
--   do {a &lt;- ma; b &lt;- mb; f a b} </tt> — the only difference is in
--   the resource utilisation. With the <a>IO</a> monad, on the other hand,
--   there may be visible difference in the results because the side
--   effects of <i>ma</i> and <i>mb</i> may be arbitrarily reordered.
module Control.Monad.Parallel

-- | Class of monads that can perform two computations in parallel and bind
--   their results together.
class Monad m => MonadParallel m where bindM2 f ma mb = let ma' = ma >>= return mb' = mb >>= return in ma' `par` (mb' `pseq` do { a <- ma'; b <- mb'; f a b })

-- | Perform two monadic computations in parallel; when they are both
--   finished, pass the results to the function. Apart from the possible
--   ordering of side effects, this function is equivalent to <tt>\f ma
--   mb-&gt; do {a &lt;- ma; b &lt;- mb; f a b}</tt>
bindM2 :: MonadParallel m => (a -> b -> m c) -> m a -> m b -> m c

-- | Class of monads that can fork a parallel computation.
class MonadParallel m => MonadFork m where forkExec e = let result = e >>= return in result `par` (return result)

-- | Fork a child monadic computation to be performed in parallel with the
--   current one.
forkExec :: MonadFork m => m a -> m (m a)

-- | Perform three monadic computations in parallel; when they are all
--   finished, pass their results to the function.
bindM3 :: MonadParallel m => (a -> b -> c -> m d) -> m a -> m b -> m c -> m d

-- | Like <a>ap</a>, but evaluating the function and its argument in
--   parallel.
ap :: MonadParallel m => m (a -> b) -> m a -> m b

-- | Like <a>forM</a>, but applying the function to the individual list
--   items in parallel.
forM :: MonadParallel m => [a] -> (a -> m b) -> m [b]

-- | Like <a>forM_</a>, but applying the function to the individual list
--   items in parallel.
forM_ :: MonadParallel m => [a] -> (a -> m b) -> m ()

-- | Like <a>liftM2</a>, but evaluating its two monadic arguments in
--   parallel.
liftM2 :: MonadParallel m => (a -> b -> c) -> m a -> m b -> m c

-- | Like <a>liftM3</a>, but evaluating its three monadic arguments in
--   parallel.
liftM3 :: (MonadParallel m) => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r

-- | Like <a>mapM</a>, but applying the function to the individual list
--   items in parallel.
mapM :: MonadParallel m => (a -> m b) -> [a] -> m [b]

-- | Like <a>mapM_</a>, but applying the function to the individual list
--   items in parallel.
mapM_ :: MonadParallel m => (a -> m b) -> [a] -> m ()

-- | Like <a>replicateM</a>, but executing the action multiple times in
--   parallel.
replicateM :: MonadParallel m => Int -> m a -> m [a]

-- | Like <a>replicateM_</a>, but executing the action multiple times in
--   parallel.
replicateM_ :: MonadParallel m => Int -> m a -> m ()

-- | Like <a>sequence</a>, but executing the actions in parallel.
sequence :: MonadParallel m => [m a] -> m [a]

-- | Like <a>sequence_</a>, but executing the actions in parallel.
sequence_ :: MonadParallel m => [m a] -> m ()
instance Control.Monad.Parallel.MonadParallel Data.Functor.Identity.Identity
instance Control.Monad.Parallel.MonadParallel GHC.Base.Maybe
instance Control.Monad.Parallel.MonadParallel []
instance Control.Monad.Parallel.MonadParallel ((->) r)
instance Control.Monad.Parallel.MonadParallel GHC.Types.IO
instance Control.Monad.Parallel.MonadParallel m => Control.Monad.Parallel.MonadParallel (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Parallel.MonadParallel m => Control.Monad.Parallel.MonadParallel (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.Parallel.MonadParallel m => Control.Monad.Parallel.MonadParallel (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.Parallel.MonadParallel m => Control.Monad.Parallel.MonadParallel (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Parallel.MonadParallel m => Control.Monad.Parallel.MonadParallel (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Parallel.MonadFork GHC.Base.Maybe
instance Control.Monad.Parallel.MonadFork []
instance Control.Monad.Parallel.MonadFork ((->) r)
instance Control.Monad.Parallel.MonadFork GHC.Types.IO
instance Control.Monad.Parallel.MonadFork m => Control.Monad.Parallel.MonadFork (Control.Monad.Trans.Identity.IdentityT m)
instance Control.Monad.Parallel.MonadFork m => Control.Monad.Parallel.MonadFork (Control.Monad.Trans.Maybe.MaybeT m)
instance Control.Monad.Parallel.MonadFork m => Control.Monad.Parallel.MonadFork (Control.Monad.Trans.Except.ExceptT e m)
instance Control.Monad.Parallel.MonadFork m => Control.Monad.Parallel.MonadFork (Control.Monad.Trans.List.ListT m)
instance Control.Monad.Parallel.MonadFork m => Control.Monad.Parallel.MonadFork (Control.Monad.Trans.Reader.ReaderT r m)
