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


-- | Cloud Haskell Async API
--   
--   This package provides a higher-level interface over Processes, in
--   which an Async a is a concurrent, possibly distributed Process that
--   will eventually deliver a value of type a. The package provides ways
--   to create Async computations, wait for their results, and cancel them.
@package distributed-process-async
@version 0.2.6


-- | This API provides a means for spawning asynchronous operations,
--   waiting for their results, cancelling them and various other
--   utilities. Asynchronous operations can be executed on remote nodes.
--   
--   <ul>
--   <li><i>Asynchronous Operations</i></li>
--   </ul>
--   
--   There is an implicit contract for async workers; Workers must exit
--   normally (i.e., should not call the <a>exit</a>, <a>die</a> or
--   <a>terminate</a> Cloud Haskell primitives), otherwise the
--   <a>AsyncResult</a> will end up being <tt>AsyncFailed
--   DiedException</tt> instead of containing the result.
--   
--   Portions of this file are derived from the
--   <tt>Control.Concurrent.Async</tt> module, from the <tt>async</tt>
--   package written by Simon Marlow.
module Control.Distributed.Process.Async

-- | A reference to an asynchronous action
type AsyncRef = ProcessId

-- | A task to be performed asynchronously.
data AsyncTask a
AsyncTask :: Process a -> AsyncTask a

-- | the task to be performed
[asyncTask] :: AsyncTask a -> Process a
AsyncRemoteTask :: Static (SerializableDict a) -> NodeId -> Closure (Process a) -> AsyncTask a

-- | the serializable dict required to spawn a remote process
[asyncTaskDict] :: AsyncTask a -> Static (SerializableDict a)

-- | the node on which to spawn the asynchronous task
[asyncTaskNode] :: AsyncTask a -> NodeId

-- | the task to be performed, wrapped in a closure environment
[asyncTaskProc] :: AsyncTask a -> Closure (Process a)

-- | An handle for an asynchronous action spawned by <tt>async</tt>.
--   Asynchronous operations are run in a separate process, and operations
--   are provided for waiting for asynchronous actions to complete and
--   obtaining their results (see e.g. <tt>wait</tt>).
--   
--   Handles of this type cannot cross remote boundaries, nor are they
--   <tt>Serializable</tt>.
data Async a

-- | Represents the result of an asynchronous action, which can be in one
--   of several states at any given time.
data AsyncResult a

-- | a completed action and its result
AsyncDone :: a -> AsyncResult a

-- | a failed action and the failure reason
AsyncFailed :: DiedReason -> AsyncResult a

-- | a link failure and the reason
AsyncLinkFailed :: DiedReason -> AsyncResult a

-- | a cancelled action
AsyncCancelled :: AsyncResult a

-- | a pending action (that is still running)
AsyncPending :: AsyncResult a

-- | Spawns an asynchronous action and returns a handle to it, which can be
--   used to obtain its status and/or result or interact with it (using the
--   API exposed by this module).
async :: (Serializable a) => AsyncTask a -> Process (Async a)

-- | This is a useful variant of <a>async</a> that ensures an
--   <tt>Async</tt> task is never left running unintentionally. We ensure
--   that if the caller's process exits, that the worker is killed.
--   
--   There is currently a contract for async workers, that they should exit
--   normally (i.e., they should not call the <tt>exit</tt> or
--   <tt>kill</tt> with their own <a>ProcessId</a> nor use the
--   <tt>terminate</tt> primitive to cease functining), otherwise the
--   <a>AsyncResult</a> will end up being <tt>AsyncFailed
--   DiedException</tt> instead of containing the desired result.
asyncLinked :: (Serializable a) => AsyncTask a -> Process (Async a)

-- | Wraps a regular <tt>Process a</tt> as an <a>AsyncTask</a>.
task :: Process a -> AsyncTask a

-- | Wraps the components required and builds a remote <a>AsyncTask</a>.
remoteTask :: Static (SerializableDict a) -> NodeId -> Closure (Process a) -> AsyncTask a

-- | Given an <a>Async</a> handle, monitor the worker process.
monitorAsync :: Async a -> Process MonitorRef

-- | Provides the pid of the worker process performing the async operation.
asyncWorker :: Async a -> ProcessId

-- | Cancel an asynchronous operation.
cancel :: Async a -> Process ()

-- | Cancel an asynchronous operation and wait for the cancellation to
--   complete.
cancelWait :: (Serializable a) => Async a -> Process (AsyncResult a)

-- | Cancel an asynchronous operation immediately.
cancelWith :: (Serializable b) => b -> Async a -> Process ()

-- | Like <a>cancelWith</a> but sends a <tt>kill</tt> instruction instead
--   of an exit.
cancelKill :: String -> Async a -> Process ()

-- | Check whether an <a>Async</a> has completed yet.
poll :: (Serializable a) => Async a -> Process (AsyncResult a)

-- | Like <a>poll</a> but returns <a>Nothing</a> if <tt>(poll hAsync) ==
--   AsyncPending</tt>.
check :: (Serializable a) => Async a -> Process (Maybe (AsyncResult a))

-- | Wait for an asynchronous action to complete, and return its value. The
--   result (which can include failure and/or cancellation) is encoded by
--   the <a>AsyncResult</a> type.
--   
--   <pre>
--   wait = liftIO . atomically . waitSTM
--   </pre>
wait :: Async a -> Process (AsyncResult a)

-- | Wait for any of the supplied <tt>Async</tt>s to complete. If multiple
--   <a>Async</a>s complete, then the value returned corresponds to the
--   first completed <a>Async</a> in the list.
--   
--   NB: Unlike <tt>AsyncChan</tt>, <a>Async</a> does not discard its
--   <a>AsyncResult</a> once read, therefore the semantics of this function
--   are different to the former. Specifically, if <tt>asyncs = [a1, a2,
--   a3]</tt> and <tt>(AsyncDone _) = a1</tt> then the remaining <tt>a2,
--   a3</tt> will never be returned by <a>waitAny</a>.
waitAny :: (Serializable a) => [Async a] -> Process (Async a, AsyncResult a)

-- | Like <a>waitAny</a> but times out after the specified delay.
waitAnyTimeout :: (Serializable a) => Int -> [Async a] -> Process (Maybe (AsyncResult a))

-- | Wait for an asynchronous operation to complete or timeout.
waitTimeout :: (Serializable a) => Int -> Async a -> Process (Maybe (AsyncResult a))

-- | Wait for an asynchronous operation to complete or timeout. If it times
--   out, then <a>cancelWait</a> the async handle.
waitCancelTimeout :: (Serializable a) => Int -> Async a -> Process (AsyncResult a)

-- | Wait for an asynchronous operation to complete or timeout.
waitCheckTimeout :: (Serializable a) => Int -> Async a -> Process (AsyncResult a)

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

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

-- | STM version of <a>waitAny</a>.
waitAnySTM :: [Async a] -> IO (Async a, AsyncResult a)

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

-- | Wait for the first of two <tt>Async</tt>s to finish.
waitEither :: Async a -> Async b -> Process (Either (AsyncResult a) (AsyncResult b))

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

-- | Waits for both <tt>Async</tt>s to finish.
waitBoth :: Async a -> Async b -> Process (AsyncResult a, AsyncResult b)