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


-- | Write once concurrency primitives.
--   
--   <tt>IVar</tt>s are write-once (immutable) variables.
--   
--   They can be read, an operation that will block until a value was
--   written to the variable. They can be written to exactly once.
@package ivar-simple
@version 0.2


-- | <a>IVar</a>s are write-once variables.
--   
--   Similarily to <a>MVar</a>s, <a>IVar</a>s can be either empty or
--   filled. Once filled, they keep their value indefinitely - they are
--   immutable.
--   
--   Reading from an empty <a>IVar</a> will block until the <a>IVar</a> is
--   filled. Because the value read will never change, this is a pure
--   computation.
module Data.IVar.Simple

-- | A write-once (<i>immutable</i>) Variable
data IVar a

-- | Creates a new, empty <a>IVar</a>.
new :: IO (IVar a)

-- | Create a new filled <a>IVar</a>.
--   
--   This is slightly cheaper than creating a new <a>IVar</a> and then
--   writing to it.
newFull :: a -> IO (IVar a)

-- | Returns the value of an <a>IVar</a>.
--   
--   The evaluation will block until a value is written to the <a>IVar</a>
--   if there is no value yet.
read :: IVar a -> a

-- | Try to read an <a>IVar</a>. Returns <a>Nothing</a> if there is not
--   value yet.
tryRead :: IVar a -> IO (Maybe a)

-- | Writes a value to an <a>IVar</a>. Raises a <a>NonTermination</a>
--   exception if it fails.
write :: IVar a -> a -> IO ()

-- | Writes a value to an <a>IVar</a>. Returns <a>True</a> if successful.
tryWrite :: IVar a -> a -> IO Bool


-- | An <a>IChan</a>s is a type of multicast channel built on top of
--   <a>IVar</a>s. It supports multiple readers. The <a>IChan</a> data type
--   represents the head of a channel.
--   
--   Writing to an <a>IChan</a> head has write-once semantics similar to
--   <a>IVar</a>s: only the first of several attempts to write to the head
--   will succeed, returning a new <a>IChan</a> head for writing more
--   values.
module Data.IVar.Simple.IChan

-- | A channel head
data IChan a

-- | Create a new channel.
new :: IO (IChan a)

-- | Returns the contents of a channel as a list, starting at the channel
--   head.
--   
--   This is a pure computation. Forcing elements of the list may, however,
--   block.
read :: IChan a -> [a]

-- | Write a single value to the channel.
--   
--   Raises a <tt>NonTermination</tt> exception if a value has already been
--   written to the channel. Otherwise, returns a new channel head for
--   writing further values.
write :: IChan a -> a -> IO (IChan a)

-- | Attempts to write a single value to the channel.
--   
--   If a value has already been written, returns <a>Nothing</a>.
--   Otherwise, returns a new channel head for writing further values.
tryWrite :: IChan a -> a -> IO (Maybe (IChan a))


-- | An <a>MIChan</a> is a multicast channel built on top of an
--   <a>IChan</a>.
--   
--   Like <a>IChan</a>, this supports multiple readers. It is comparable to
--   a <tt>Control.Concurrent.Chan.Chan</tt> for the writing end: Each
--   write will append an element to the channel. No writes will fail.
module Data.IVar.Simple.MIChan

-- | A multicast channel.
data MIChan a

-- | Create a new multicast channel.
new :: IO (MIChan a)

-- | Return the list of values that the channel represents.
read :: MIChan a -> IO [a]

-- | Send a value across the channel.
write :: MIChan a -> a -> IO ()

-- | Send several values across the channel, atomically.
writeList :: MIChan a -> [a] -> IO ()