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


-- | Write-once variables with concurrency support
--   
--   Write-once variables, with the ability to block on the first of a set
--   of variables to become available.
@package data-ivar
@version 0.1


-- | An IVar is an write-once variable (the name comes from "immutable
--   variable"). In addition to encapsulating this common idiom, it also
--   provides a way to block on multiple variables simultaneously, resuming
--   when the first of them is written.
--   
--   This module is careful not to create memory leaks, and prefers to
--   maintain good long-term memory performance than to be super-fast. It
--   should be reasonably fast though.
--   
--   This module is designed to be imported qualified, as in:
--   
--   <pre>
--   import qualified Data.IVar as IVar
--   </pre>
--   
--   Example:
--   
--   <pre>
--   import qualified Data.IVar as IVar
--   import Control.Concurrent
--   
--   main = do
--      iv &lt;- IVar.new
--      iv' &lt;- IVar.new
--      forkIO $ threadDelay 10000000 &gt;&gt; writeIVar iv' "my spoon is too big"
--      let merger = IVar.read iv `mplus` IVar.read iv'
--      print =&lt;&lt; IVar.nonblocking merger   -- most likely "Nothing"
--      print =&lt;&lt; IVar.blocking merger      -- waits a while, then prints
--      writeIVar iv' "i am a banana"       -- throws error "IVar written twice"
--   </pre>
module Data.IVar

-- | A write-once variable.
data IVar a

-- | Create a new empty IVar.
new :: IO (IVar a)

-- | Write a value to an IVar. If the IVar already has a value, throws an
--   error <a>Attempt to write to an IVar twice</a>.
write :: IVar a -> a -> IO ()

-- | Read an IVar into the <a>Reader</a> functor. Pass this to
--   <a>blocking</a> or <a>nonblocking</a> to extract the value.
read :: IVar a -> Reader a

-- | Reader is a functor (also monad) for reading IVars. This provides
--   composability when blocking on the first of a set of IVars, as you can
--   block on several IVars of different types.
--   
--   The MonadPlus and Monoid instances for Reader are equivalent. It tries
--   the left action ; if it blocks, then it tries the right action ; if
--   *it* blocks, then the whole action blocks until one of the two is
--   available.
data Reader a

-- | Run a reader nonblocking. Returns Just x if a value x is available,
--   Nothing otherwise.
nonblocking :: Reader a -> IO (Maybe a)

-- | Block on a reader. Returns the value as soon as it is available.
blocking :: Reader a -> IO a
instance MonadPlus Reader
instance Monoid (Reader a)
instance Applicative Reader
instance Monad Reader
instance Functor Reader
instance Functor LogEntry