-- 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


-- | 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
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
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 <tt>Control.Monad.liftM2</tt>, but evaluating its two monadic
--   arguments in parallel.
liftM2 :: MonadParallel m => (a -> b -> c) -> m a -> m b -> m c

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

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

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

-- | Like <tt>Control.Monad.sequence_</tt>, but executing the actions in
--   parallel.
sequence_ :: MonadParallel m => [m a] -> m ()

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

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

-- | Like <tt>Control.Monad.replicateM_</tt>, but executing the action
--   multiple times in parallel.
replicateM_ :: MonadParallel m => Int -> m a -> m ()
instance MonadFork m => MonadFork (ReaderT r m)
instance MonadFork m => MonadFork (ListT m)
instance (MonadFork m, Error e) => MonadFork (ErrorT e m)
instance MonadFork m => MonadFork (MaybeT m)
instance MonadFork m => MonadFork (IdentityT m)
instance MonadFork IO
instance MonadFork ((->) r)
instance MonadFork []
instance MonadFork Maybe
instance MonadParallel m => MonadParallel (ReaderT r m)
instance MonadParallel m => MonadParallel (ListT m)
instance (MonadParallel m, Error e) => MonadParallel (ErrorT e m)
instance MonadParallel m => MonadParallel (MaybeT m)
instance MonadParallel m => MonadParallel (IdentityT m)
instance MonadParallel IO
instance MonadParallel ((->) r)
instance MonadParallel []
instance MonadParallel Maybe
instance MonadParallel Identity