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


-- | Run MonadConc operations asynchronously and wait for their results.
--   
--   The <a>async</a> library provides a higher-level interface over
--   threads, allowing users to conveniently run IO operations
--   asynchronously and wait for their results. This package is a
--   reimplementation of async using the <tt>MonadConc</tt> abstraction
--   from <a>concurrency</a>, providing easy-to-use asynchronous operaitons
--   within an easily-testable framework.
--   
--   This library itself is tested with <a>dejafu</a>.
--   
--   When these functions are used in an IO context, the behaviour should
--   appear identical to the original async package.
@package async-dejafu
@version 0.1.3.0


-- | This module is a version of the <a>async</a> package using the
--   <a>dejafu</a> concurrency abstraction. It provides a set of operations
--   for running <tt>MonadConc</tt> operations asynchronously and waiting
--   for their results.
--   
--   For example, assuming a suitable <tt>getURL</tt> function, we can
--   fetch the contents of two web pages at the same time:
--   
--   <pre>
--   withAsync (getURL url1) $ \a1 -&gt; do
--   withAsync (getURL url2) $ \a2 -&gt; do
--   page1 &lt;- wait a1
--   page2 &lt;- wait a2
--   ...
--   </pre>
--   
--   The <a>withAsync</a> function starts an operation in a separate
--   thread, and kills it if the inner action finishes before it completes.
--   
--   There are a few deviations from the regular async package:
--   
--   <ul>
--   <li><tt>asyncBound</tt> and <tt>withAsyncBound</tt> are missing as
--   dejafu does not support bound threads.</li>
--   <li>The <tt>Alternative</tt> instance for <a>Concurrently</a> uses
--   <tt>forever yield</tt> in the definition of <tt>empty</tt>, rather
--   than <tt>forever (threadDelay maxBound)</tt>.</li>
--   </ul>
module Control.Concurrent.Async

-- | An asynchronous action spawned by <a>async</a> or <a>withAsync</a>.
--   Asynchronous actions are executed in a separate thread, and operations
--   are provided for waiting for asynchronous actions to complete and
--   obtaining their results (see e.g. <a>wait</a>).
--   
--   Note that, unlike the "async" package, <a>Async</a> here does not have
--   an <a>Ord</a> instance. This is because <a>MonadConc</a>
--   <a>ThreadId</a>s do not necessarily have one.
data Async m a

-- | Spawn an asynchronous action in a separate thread.
async :: MonadConc m => m a -> m (Async m a)

-- | Like <a>async</a> but using <a>forkOn</a> internally.
asyncOn :: MonadConc m => Int -> m a -> m (Async m a)

-- | Like <a>async</a> but using <a>forkWithUnmask</a> internally.
asyncWithUnmask :: MonadConc m => ((forall b. m b -> m b) -> m a) -> m (Async m a)

-- | Like <a>asyncOn</a> but using <a>forkOnWithUnmask</a> internally.
asyncOnWithUnmask :: MonadConc m => Int -> ((forall b. m b -> m b) -> m a) -> m (Async m a)

-- | Spawn an asynchronous action in a separate thread, and pass its
--   <tt>Async</tt> handle to the supplied function. When the function
--   returns or throws an exception, <a>cancel</a> is called on the
--   <tt>Async</tt>.
--   
--   <pre>
--   withAsync action inner = bracket (async action) cancel inner
--   </pre>
--   
--   This is a useful variant of <a>async</a> that ensures an
--   <tt>Async</tt> is never left running unintentionally.
--   
--   Since <a>cancel</a> may block, <a>withAsync</a> may also block; see
--   <a>cancel</a> for details.
withAsync :: MonadConc m => m a -> (Async m a -> m b) -> m b

-- | Like <a>withAsync</a> but uses <a>forkOn</a> internally.
withAsyncOn :: MonadConc m => Int -> m a -> (Async m a -> m b) -> m b

-- | Like <a>withAsync</a> bit uses <a>forkWithUnmask</a> internally.
withAsyncWithUnmask :: MonadConc m => ((forall x. m x -> m x) -> m a) -> (Async m a -> m b) -> m b

-- | Like <a>withAsyncOn</a> bit uses <a>forkOnWithUnmask</a> internally.
withAsyncOnWithUnmask :: MonadConc m => Int -> ((forall x. m x -> m x) -> m a) -> (Async m a -> m b) -> m b

-- | Wait for an asynchronous action to complete, and return its value. If
--   the asynchronous value threw an exception, then the exception is
--   re-thrown by <a>wait</a>.
--   
--   <pre>
--   wait = atomically . waitSTM
--   </pre>
wait :: MonadConc m => Async m a -> m a

-- | A version of <a>wait</a> that can be used inside a <tt>MonadSTM</tt>
--   transaction.
waitSTM :: MonadConc m => Async m a -> STM m a

-- | Check whether an <a>Async</a> has completed yet. If it has not
--   completed yet, then the result is <tt>Nothing</tt>, otherwise the
--   result is <tt>Just e</tt> where <tt>e</tt> is <tt>Left x</tt> if the
--   <tt>Async</tt> raised an exception <tt>x</tt>, or <tt>Right a</tt> if
--   it returned a value <tt>a</tt>.
--   
--   <pre>
--   poll = atomically . pollSTM
--   </pre>
poll :: MonadConc m => Async m a -> m (Maybe (Either SomeException a))

-- | A version of <a>poll</a> that can be used inside a <tt>MonadSTM</tt>
--   transaction.
pollSTM :: MonadConc m => Async m a -> STM m (Maybe (Either SomeException a))

-- | Wait for an asynchronous action to complete, and return either
--   <tt>Left e</tt> if the action raised an exception <tt>e</tt>, or
--   <tt>Right a</tt> if it returned a value <tt>a</tt>.
waitCatch :: MonadConc m => Async m a -> m (Either SomeException a)

-- | A version of <a>waitCatch</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitCatchSTM :: MonadConc m => Async m a -> STM m (Either SomeException a)

-- | Cancel an asynchronous action by throwing the <tt>ThreadKilled</tt>
--   exception to it. Has no effect if the <a>Async</a> has already
--   completed.
--   
--   <pre>
--   cancel a = throwTo (asyncThreadId a) ThreadKilled
--   </pre>
--   
--   Note that <a>cancel</a> is synchronous in the same sense as
--   <a>throwTo</a>. It does not return until the exception has been thrown
--   in the target thread, or the target thread has completed. An
--   asynchronous <a>cancel</a> can of course be obtained by wrapping
--   <a>cancel</a> itself in <a>async</a>.
cancel :: MonadConc m => Async m a -> m ()

-- | Cancel an asynchronous action by throwing the supplied exception to
--   it.
--   
--   <pre>
--   cancelWith a e = throwTo (asyncThreadId a) e
--   </pre>
--   
--   The notes about the synchronous nature of <a>cancel</a> also apply to
--   <a>cancelWith</a>.
cancelWith :: (MonadConc m, Exception e) => Async m a -> e -> m ()
asyncThreadId :: Async m a -> (ThreadId m)

-- | Wait for any of the supplied <a>Async</a>s to complete. If the first
--   to complete throws an exception, then that exception is re-thrown by
--   <a>waitAny</a>.
--   
--   If multiple <a>Async</a>s complete or have completed, then the value
--   returned corresponds to the first completed <a>Async</a> in the list.
waitAny :: MonadConc m => [Async m a] -> m (Async m a, a)

-- | A version of <a>waitAny</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitAnySTM :: MonadConc m => [Async m a] -> STM m (Async m a, a)

-- | Wait for any of the supplied asynchronous operations to complete. The
--   value returned is a pair of the <a>Async</a> that completed, and the
--   result that would be returned by <a>wait</a> on that <a>Async</a>.
--   
--   If multiple <a>Async</a>s complete or have completed, then the value
--   returned corresponds to the first completed <a>Async</a> in the list.
waitAnyCatch :: MonadConc m => [Async m a] -> m (Async m a, Either SomeException a)

-- | A version of <a>waitAnyCatch</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitAnyCatchSTM :: MonadConc m => [Async m a] -> STM m (Async m a, Either SomeException a)

-- | Like <a>waitAny</a>, but also cancels the other asynchronous
--   operations as soon as one has completed.
waitAnyCancel :: MonadConc m => [Async m a] -> m (Async m a, a)

-- | Like <a>waitAnyCatch</a>, but also cancels the other asynchronous
--   operations as soon as one has completed.
waitAnyCatchCancel :: MonadConc m => [Async m a] -> m (Async m a, Either SomeException a)

-- | Wait for the first of two <tt>Async</tt>s to finish. If the
--   <tt>Async</tt> that finished first raised an exception, then the
--   exception is re-thrown by <a>waitEither</a>.
waitEither :: MonadConc m => Async m a -> Async m b -> m (Either a b)

-- | A version of <a>waitEither</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitEitherSTM :: MonadConc m => Async m a -> Async m b -> STM m (Either a b)

-- | Wait for the first of two <tt>Async</tt>s to finish.
waitEitherCatch :: MonadConc m => Async m a -> Async m b -> m (Either (Either SomeException a) (Either SomeException b))

-- | A version of <a>waitEitherCatch</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitEitherCatchSTM :: MonadConc m => Async m a -> Async m b -> STM m (Either (Either SomeException a) (Either SomeException b))

-- | Like <a>waitEither</a>, but also <a>cancel</a>s both <tt>Async</tt>s
--   before returning.
waitEitherCancel :: MonadConc m => Async m a -> Async m b -> m (Either a b)

-- | Like <a>waitEitherCatch</a>, but also <a>cancel</a>s both
--   <tt>Async</tt>s before returning.
waitEitherCatchCancel :: MonadConc m => Async m a -> Async m b -> m (Either (Either SomeException a) (Either SomeException b))

-- | Like <a>waitEither</a>, but the result is ignored.
waitEither_ :: MonadConc m => Async m a -> Async m b -> m ()

-- | A version of <a>waitEither_</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitEitherSTM_ :: MonadConc m => Async m a -> Async m b -> STM m ()

-- | Waits for both <tt>Async</tt>s to finish, but if either of them throws
--   an exception before they have both finished, then the exception is
--   re-thrown by <a>waitBoth</a>.
waitBoth :: MonadConc m => Async m a -> Async m b -> m (a, b)

-- | A version of <a>waitBoth</a> that can be used inside a
--   <tt>MonadSTM</tt> transaction.
waitBothSTM :: MonadConc m => Async m a -> Async m b -> STM m (a, b)

-- | Link the given <tt>Async</tt> to the current thread, such that if the
--   <tt>Async</tt> raises an exception, that exception will be re-thrown
--   in the current thread.
link :: MonadConc m => Async m a -> m ()

-- | Link two <tt>Async</tt>s together, such that if either raises an
--   exception, the same exception is re-thrown in the other
--   <tt>Async</tt>.
link2 :: MonadConc m => Async m a -> Async m b -> m ()

-- | Run two <tt>MonadConc</tt> actions concurrently, and return the first
--   to finish. The loser of the race is <a>cancel</a>led.
--   
--   <pre>
--   race left right =
--     withAsync left $ \a -&gt;
--     withAsync right $ \b -&gt;
--     waitEither a b
--   </pre>
race :: MonadConc m => m a -> m b -> m (Either a b)

-- | Like <a>race</a>, but the result is ignored.
--   
--   <pre>
--   race_ left right =
--     withAsync left $ \a -&gt;
--     withAsync right $ \b -&gt;
--     waitEither_ a b
--   </pre>
race_ :: MonadConc m => m a -> m b -> m ()

-- | Run two <tt>MonadConc</tt> actions concurrently, and return both
--   results. If either action throws an exception at any time, then the
--   other action is <a>cancel</a>led, and the exception is re-thrown by
--   <a>concurrently</a>.
--   
--   <pre>
--   concurrently left right =
--     withAsync left $ \a -&gt;
--     withAsync right $ \b -&gt;
--     waitBoth a b
--   </pre>
concurrently :: MonadConc m => m a -> m b -> m (a, b)

-- | Maps a <tt>MonadConc</tt>-performing function over any
--   <tt>Traversable</tt> data type, performing all the <tt>MonadConc</tt>
--   actions concurrently, and returning the original data structure with
--   the arguments replaced by the results.
--   
--   For example, <tt>mapConcurrently</tt> works with lists:
--   
--   <pre>
--   pages &lt;- mapConcurrently getURL ["url1", "url2", "url3"]
--   </pre>
mapConcurrently :: (Traversable t, MonadConc m) => (a -> m b) -> t a -> m (t b)

-- | <a>forConcurrently</a> is <a>mapConcurrently</a> with its arguments
--   flipped
--   
--   <pre>
--   pages &lt;- forConcurrently ["url1", "url2", "url3"] $ \url -&gt; getURL url
--   </pre>
forConcurrently :: (Traversable t, MonadConc m) => t a -> (a -> m b) -> m (t b)

-- | A value of type <tt>Concurrently m a</tt> is a <tt>MonadConc</tt>
--   operation that can be composed with other <tt>Concurrently</tt>
--   values, using the <tt>Applicative</tt> and <tt>Alternative</tt>
--   instances.
--   
--   Calling <tt>runConcurrently</tt> on a value of type <tt>Concurrently m
--   a</tt> will execute the <tt>MonadConc</tt> operations it contains
--   concurrently, before delivering the result of type <tt>a</tt>.
--   
--   For example
--   
--   <pre>
--   (page1, page2, page3)
--     &lt;- runConcurrently $ (,,)
--     &lt;$&gt; Concurrently (getURL "url1")
--     &lt;*&gt; Concurrently (getURL "url2")
--     &lt;*&gt; Concurrently (getURL "url3")
--   </pre>
newtype Concurrently m a
Concurrently :: m a -> Concurrently m a
[runConcurrently] :: Concurrently m a -> m a
instance Control.Monad.Conc.Class.MonadConc m => GHC.Base.Functor (Control.Concurrent.Async.Concurrently m)
instance Control.Monad.Conc.Class.MonadConc m => GHC.Base.Applicative (Control.Concurrent.Async.Concurrently m)
instance Control.Monad.Conc.Class.MonadConc m => GHC.Base.Alternative (Control.Concurrent.Async.Concurrently m)
instance Control.Monad.Conc.Class.MonadConc m => GHC.Classes.Eq (Control.Concurrent.Async.Async m a)
instance Control.Monad.Conc.Class.MonadConc m => GHC.Base.Functor (Control.Concurrent.Async.Async m)
