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


-- | Lazy demand-driven promises
--   
--   Lazy demand-driven promises
@package promises
@version 0.3


-- | Lazy demand-driven promises.
module Data.Promise

-- | A lazy, demand-driven calculation that can create and fulfill
--   promises.
data Lazy s a

-- | Run a lazy computation. The final answer is given in the form of a
--   promise to be fulfilled. If the promises is unfulfilled then an user
--   supplied default value will be returned.
runLazy :: (forall s. Promise s a -> Lazy s b) -> a -> a

-- | Run a lazy computation. The final answer is given in the form of a
--   promise to be fulfilled. If the promises is unfulfilled then an
--   <a>BrokenPromise</a> will be thrown.
--   
--   <pre>
--   <a>runLazy_</a> k ≡ <a>runLazy</a> k (<a>throw</a> <a>BrokenPromise</a>)
--   </pre>
runLazy_ :: (forall s. Promise s a -> Lazy s b) -> a
runLazyIO :: (forall s. Promise s a -> Lazy s b) -> a -> IO a
runLazyIO_ :: (forall s. Promise s a -> Lazy s b) -> IO a

-- | A lazy I-Var.
data Promise s a
Promise :: MVar a -> a -> Promise s a

-- | Promise that by the end of the computation we'll provide a "real"
--   answer, or we'll fall back and give you this answer
promise :: a -> Lazy s (Promise s a)

-- | Create an empty promise. If you observe the demanded answer of this
--   promise then either by the end of the current lazy computation we'll
--   provide a "real" answer, or you'll get an error.
--   
--   <pre>
--   <a>promise_</a> ≡ <a>promise</a> (<a>throw</a> <a>BrokenPromise</a>)
--   </pre>
promise_ :: Lazy s (Promise s a)

-- | Fulfill a promise. Each promise should only be fulfilled once.
--   
--   <pre>
--   &gt;&gt;&gt; runLazy_ $ \p -&gt; p != "good"
--   "good"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runLazy_ $ \p -&gt; do q &lt;- promise_; p != "yay! " ++ demand q; q != "it works."
--   "yay! it works."
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runLazy_ $ \p -&gt; return ()
--   *** Exception: BrokenPromise
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; runLazy (\p -&gt; return ()) "default"
--   "default"
--   </pre>
(!=) :: Promise s a -> a -> Lazy s ()

-- | Demand the result of a promise.
demand :: Promise s a -> a

-- | Thrown when the answer for an unfulfillable promise is demanded.
data BrokenPromise
BrokenPromise :: BrokenPromise
instance GHC.Show.Show Data.Promise.BrokenPromise
instance GHC.Exception.Exception Data.Promise.BrokenPromise
instance GHC.Base.Functor (Data.Promise.Lazy s)
instance GHC.Base.Applicative (Data.Promise.Lazy s)
instance GHC.Base.Monad (Data.Promise.Lazy s)
instance Control.Monad.Primitive.PrimMonad (Data.Promise.Lazy s)
instance Control.Monad.Fix.MonadFix (Data.Promise.Lazy s)
instance GHC.Base.Functor (Data.Promise.K s)