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


-- | Supposed to mimics and enhance proposed C++ "future" features
--   
--   Similar to <a>futures</a> in C++ (with support for cotinuations). This
--   differs from IVars in that the value is from an action in a spawned
--   thread, and exceptions are caught and returned.
@package future
@version 1.1.0


-- | This <a>Future</a> module was written by Chris Kuklewicz to see if he
--   understood the design and utility of the new C++ standard's future. In
--   particular the ability to cleanly access either a resulting value or
--   exception.
--   
--   There a methods to poll (with <a>check</a>), to block (with
--   <a>wait</a> or <a>timedWait</a>), and to block and retrieve the actual
--   value or rethrow the exception in the accessing thread (with
--   <a>get</a> or <a>timedGet</a>). Timeouts are in micro seconds, values
--   less than or equal to zero use non-blocking <a>check</a>. The timeout
--   should be detected reagarless of the blocking or FFI state of the
--   worker thread.
--   
--   One can also manage the threadBy calling <a>abort</a>, which may cause
--   the promise to store the exception from the abort as well as killing
--   the worker thread. The worker thread Id is a secret, this is needed to
--   ensure the running of the continuations. The <a>abort</a> operation
--   has the same synchronous behavior as <a>killThread</a>.
--   
--   Note: There is no way for an outside thread to directly set the value
--   of the promise to a non-exception value. Using <a>abort</a> (or
--   <tt>throwTo</tt> with <tt>getPromiseThreadId</tt>) creates a race
--   condition in setting the result of the promise. There is no way to
--   change the result of promise once it has been set.
--   
--   The extension to the C++ standard is in the continuation attachment.
--   The <a>addTodo</a> command will, while the worker is running, add the
--   <tt>todo</tt> continuation to an internal list. Immediately upon
--   finishing the action the worker thread will always run through the
--   queued continuations. Each <tt>todo</tt> will be run in its own forkIO
--   thread (unblocked). If the <a>addTodo</a> command is issued after the
--   promise value has been set then it simplify runs the <tt>todo</tt> in
--   a new thread. Thus there is no way multiple continuations can
--   interfere with each other, and there are no ordering guarantees
--   between them. The <tt>todo</tt> action will not be able to distinguish
--   whether it is being run from the stored queue or immediately.
--   
--   The use of <a>block</a> and <a>finally</a> should ensure that no
--   matter how the worker ends the stored continations are run. For
--   instnace: if <a>abort</a> is used then the continations might be run
--   with that thread killing exception or with the custom
--   <a>Promise.abort</a> exception if no other result is already present.
--   
--   One use case for <a>addTodo</a> is to allow multiplexing. Several
--   promises could be given a continuation to write the results to an
--   MChan or MVar, allowing another process to block waiting for the first
--   one to finish.
module Control.Concurrent.Future
data Promise a
type PromiseResult a = Either SomeException a

-- | forkPromise take an action to run, and runs it in a new thread. This
--   is run in an <a>unblock</a> context. If the action succeeds it will
--   store its result as (Right {}). If the action throws an exception, or
--   the
forkPromise :: IO a -> IO (Promise a)
forkPromises :: [IO a] -> IO ([Promise a], Chan (PromiseResult a))
racePromises :: [IO a] -> IO (PromiseResult a)

-- | <a>check</a> is a non-blocking read. Like <a>timedWait</a> with 0
--   delay.
check :: Promise a -> IO (Maybe (PromiseResult a))

-- | <a>wait</a> is a blocking read.
wait :: Promise a -> IO (PromiseResult a)

-- | <a>get</a> is wait which rethrows a SomeException in the calling
--   thread
get :: Promise a -> IO a

-- | <a>timedWait</a> with a positive value in micro seconds is a blocking
--   read with timeout.
timedWait :: Int -> Promise a -> IO (Maybe (PromiseResult a))

-- | <a>timedGet</a> is a <a>timedWait</a> which rethrows a SomeException
--   in the calling thread
timedGet :: Int -> Promise a -> IO (Maybe a)

-- | If the abort occurs before the act has stored a result then the result
--   is set to (userError <a>Promise.abort</a> :: IOError), or the
--   killThread exception.
abort :: Promise t -> IO ()

-- | Post an action to perform in a new thread with the reasult of the
--   promise. All are run unblocked in a fresh thread.
addTodo :: Promise a -> (PromiseResult a -> IO ()) -> IO ()
instance Show (Promise a)
instance Ord (Promise a)
instance Eq (Promise a)