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


-- | Run IO operations asynchronously and wait for their results
--   
--   This package provides a higher-level interface over threads, in which
--   an <tt>Async a</tt> is a concurrent thread that will eventually
--   deliver a value of type <tt>a</tt>. The package provides ways to
--   create <tt>Async</tt> computations, wait for their results, and cancel
--   them.
--   
--   Using <tt>Async</tt> is safer than using threads in two ways:
--   
--   <ul>
--   <li>When waiting for a thread to return a result, if the thread dies
--   with an exception then the caller must either re-throw the exception
--   (<a>wait</a>) or handle it (<a>waitCatch</a>); the exception cannot be
--   ignored.</li>
--   <li>The API makes it possible to build a tree of threads that are
--   automatically killed when their parent dies (see
--   <a>withAsync</a>).</li>
--   </ul>
@package async
@version 2.1.0


-- | This module provides a set of operations for running IO operations
--   asynchronously and waiting for their results. It is a thin layer over
--   the basic concurrency operations provided by
--   <a>Control.Concurrent</a>. The main additional functionality it
--   provides is the ability to wait for the return value of a thread, but
--   the interface also provides some additional safety and robustness over
--   using threads and <tt>MVar</tt> directly.
--   
--   The basic type is <tt><a>Async</a> a</tt>, which represents an
--   asynchronous <tt>IO</tt> action that will return a value of type
--   <tt>a</tt>, or die with an exception. An <tt>Async</tt> corresponds to
--   a thread, and its <a>ThreadId</a> can be obtained with
--   <a>asyncThreadId</a>, although that should rarely be necessary.
--   
--   For example, to fetch two web pages at the same time, we could do this
--   (assuming a suitable <tt>getURL</tt> function):
--   
--   <pre>
--   do a1 &lt;- async (getURL url1)
--      a2 &lt;- async (getURL url2)
--      page1 &lt;- wait a1
--      page2 &lt;- wait a2
--      ...
--   </pre>
--   
--   where <a>async</a> starts the operation in a separate thread, and
--   <a>wait</a> waits for and returns the result. If the operation throws
--   an exception, then that exception is re-thrown by <a>wait</a>. This is
--   one of the ways in which this library provides some additional safety:
--   it is harder to accidentally forget about exceptions thrown in child
--   threads.
--   
--   A slight improvement over the previous example is this:
--   
--   <pre>
--   withAsync (getURL url1) $ \a1 -&gt; do
--   withAsync (getURL url2) $ \a2 -&gt; do
--   page1 &lt;- wait a1
--   page2 &lt;- wait a2
--   ...
--   </pre>
--   
--   <a>withAsync</a> is like <a>async</a>, except that the <a>Async</a> is
--   automatically killed (using <a>cancel</a>) if the enclosing IO
--   operation returns before it has completed. Consider the case when the
--   first <a>wait</a> throws an exception; then the second <a>Async</a>
--   will be automatically killed rather than being left to run in the
--   background, possibly indefinitely. This is the second way that the
--   library provides additional safety: using <a>withAsync</a> means we
--   can avoid accidentally leaving threads running. Furthermore,
--   <a>withAsync</a> allows a tree of threads to be built, such that
--   children are automatically killed if their parents die for any reason.
--   
--   The pattern of performing two IO actions concurrently and waiting for
--   their results is packaged up in a combinator <a>concurrently</a>, so
--   we can further shorten the above example to:
--   
--   <pre>
--   (page1, page2) &lt;- concurrently (getURL url1) (getURL url2)
--   ...
--   </pre>
--   
--   The <a>Functor</a> instance can be used to change the result of an
--   <a>Async</a>. For example:
--   
--   <pre>
--   ghci&gt; a &lt;- async (return 3)
--   ghci&gt; wait a
--   3
--   ghci&gt; wait (fmap (+1) a)
--   4
--   </pre>
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>).
data Async a

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

-- | Like <a>async</a> but using <a>forkOS</a> internally.
asyncBound :: IO a -> IO (Async a)

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

-- | Like <a>async</a> but using <a>forkIOWithUnmask</a> internally. The
--   child thread is passed a function that can be used to unmask
--   asynchronous exceptions.
asyncWithUnmask :: ((forall b. IO b -> IO b) -> IO a) -> IO (Async a)

-- | Like <a>asyncOn</a> but using <a>forkOnWithUnmask</a> internally. The
--   child thread is passed a function that can be used to unmask
--   asynchronous exceptions.
asyncOnWithUnmask :: Int -> ((forall b. IO b -> IO b) -> IO a) -> IO (Async 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 :: IO a -> (Async a -> IO b) -> IO b

-- | Like <a>withAsync</a> but uses <a>forkOS</a> internally.
withAsyncBound :: IO a -> (Async a -> IO b) -> IO b

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

-- | Like <a>withAsync</a> but uses <a>forkIOWithUnmask</a> internally. The
--   child thread is passed a function that can be used to unmask
--   asynchronous exceptions.
withAsyncWithUnmask :: ((forall c. IO c -> IO c) -> IO a) -> (Async a -> IO b) -> IO b

-- | Like <a>withAsyncOn</a> but uses <a>forkOnWithUnmask</a> internally.
--   The child thread is passed a function that can be used to unmask
--   asynchronous exceptions
withAsyncOnWithUnmask :: Int -> ((forall c. IO c -> IO c) -> IO a) -> (Async a -> IO b) -> IO b

-- | Wait for an asynchronous action to complete, and return its value. If
--   the asynchronous action threw an exception, then the exception is
--   re-thrown by <a>wait</a>.
--   
--   <pre>
--   wait = atomically . waitSTM
--   </pre>
wait :: Async a -> IO 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 :: Async a -> IO (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>.
--   
--   <pre>
--   waitCatch = atomically . waitCatchSTM
--   </pre>
waitCatch :: Async a -> IO (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. In
--   particular, if the target thread is making a foreign call, the
--   exception will not be thrown until the foreign call returns, and in
--   this case <a>cancel</a> may block indefinitely. An asynchronous
--   <a>cancel</a> can of course be obtained by wrapping <a>cancel</a>
--   itself in <a>async</a>.
cancel :: Async a -> IO ()

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

-- | Returns the <a>ThreadId</a> of the thread running the given
--   <a>Async</a>.
asyncThreadId :: Async a -> ThreadId

-- | A version of <a>wait</a> that can be used inside an STM transaction.
waitSTM :: Async a -> STM a

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

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

-- | Wait for any of the supplied <tt>Async</tt>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 :: [Async a] -> IO (Async 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 :: [Async a] -> IO (Async a, Either SomeException a)

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

-- | Like <a>waitAnyCatch</a>, but also cancels the other asynchronous
--   operations as soon as one has completed.
waitAnyCatchCancel :: [Async a] -> IO (Async 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 :: Async a -> Async b -> IO (Either a b)

-- | Wait for the first of two <tt>Async</tt>s to finish.
waitEitherCatch :: Async a -> Async b -> IO (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 :: Async a -> Async b -> IO (Either a b)

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

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

-- | 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 :: Async a -> Async b -> IO (a, b)

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

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

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

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

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

-- | A version of <a>waitBoth</a> that can be used inside an STM
--   transaction.
waitBothSTM :: Async a -> Async b -> STM (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 :: Async a -> IO ()

-- | 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 :: Async a -> Async b -> IO ()

-- | Run two <tt>IO</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 :: IO a -> IO b -> IO (Either a b)

-- | Like <a>race</a>, but the result is ignored.
race_ :: IO a -> IO b -> IO ()

-- | Run two <tt>IO</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 :: IO a -> IO b -> IO (a, b)

-- | maps an <tt>IO</tt>-performing function over any <tt>Traversable</tt>
--   data type, performing all the <tt>IO</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 => (a -> IO b) -> t a -> IO (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 => t a -> (a -> IO b) -> IO (t b)

-- | A value of type <tt>Concurrently a</tt> is an <tt>IO</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
--   a</tt> will execute the <tt>IO</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 a
Concurrently :: IO a -> Concurrently a
[runConcurrently] :: Concurrently a -> IO a
instance GHC.Classes.Eq (Control.Concurrent.Async.Async a)
instance GHC.Classes.Ord (Control.Concurrent.Async.Async a)
instance GHC.Base.Functor Control.Concurrent.Async.Async
instance GHC.Base.Functor Control.Concurrent.Async.Concurrently
instance GHC.Base.Applicative Control.Concurrent.Async.Concurrently
instance GHC.Base.Alternative Control.Concurrent.Async.Concurrently
instance Data.Semigroup.Semigroup a => Data.Semigroup.Semigroup (Control.Concurrent.Async.Concurrently a)
instance (Data.Semigroup.Semigroup a, GHC.Base.Monoid a) => GHC.Base.Monoid (Control.Concurrent.Async.Concurrently a)
