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


-- | Mutable variables with Exception handling and concurrency support.
--   
--   AVars emulate mutable variables, by providing a queue based interface
--   to interacting with the variable. Each variable runs a <a>handler</a>
--   function, which reads requests from a queue and processes them one by
--   one. They can be used in concurrent systems safely, and should handle
--   exceptions thrown by modifying functions gracefully.
@package AVar
@version 0.0.2


-- | AVars are a form of transactional variables. They internally use a
--   tail recursive function to carry the <tt>state</tt> of the variable,
--   and allow for use in concurrent systems, where actions are quaranteed
--   to happen. They are designed to cope with exceptions thrown by any
--   modifying functions.
module Data.AVar

-- | <a>AVar</a>s are the means through communication with the variable are
--   conducted. They contain a Chan that is <tt>connected</tt> to the
--   variable, and is read by the variable's <a>handler</a> function.
data AVar a

-- | A <a>Transaction</a> describes what should happen to a variable. They
--   are only used internally, and are here just for reference.
data Transaction a

-- | puts the a into the variable
Put :: a -> Transaction a

-- | reads the variable
Get :: (MVar a) -> Transaction a

-- | modifies the variable
Mod :: (a -> a) -> (MVar (Maybe SomeException)) -> Transaction a

-- | modifies the variable, returning the b result to the caller
Mod' :: (a -> (a, b)) -> (MVar (Either SomeException b)) -> Transaction a

-- | conditionally modifies a variable
Atom :: (a -> Bool) -> (a -> a) -> (a -> a) -> (MVar (Either SomeException Bool)) -> Transaction a

-- | <a>newAVar</a> creates a new variable. It forks off the <a>handler</a>
--   that does the work for the variable itself and creates a new AVar.
newAVar :: a -> IO (AVar a)

-- | Put a value into an <a>MVar</a>. If the <a>MVar</a> is currently full,
--   <a>putMVar</a> will wait until it becomes empty.
--   
--   There are two further important properties of <a>putMVar</a>:
--   
--   <ul>
--   <li><a>putMVar</a> is single-wakeup. That is, if there are multiple
--   threads blocked in <a>putMVar</a>, and the <a>MVar</a> becomes empty,
--   only one thread will be woken up. The runtime guarantees that the
--   woken thread completes its <a>putMVar</a> operation.</li>
--   <li>When multiple threads are blocked on an <a>MVar</a>, they are
--   woken up in FIFO order. This is useful for providing fairness
--   properties of abstractions built using <a>MVar</a>s.</li>
--   </ul>
putMVar :: MVar a -> a -> IO ()

-- | <a>modAVar</a> takes a function from a to a, and returns Nothing if
--   nothing went wrong, or Just e, where e is an exception thrown by the
--   function.
modAVar :: AVar a -> (a -> a) -> IO (Maybe SomeException)

-- | <a>modAVar'</a> is like modAVar, but it modifies the variable, along
--   with returning a result of type b, within an Either e b.
modAVar' :: AVar a -> (a -> (a, b)) -> IO (Either SomeException b)

-- | <a>getAVar</a> reads the current value inside the AVar.
getAVar :: AVar a -> IO a

-- | <a>condModAVar</a> applies the first finction to the current value in
--   the AVar, and if true will modify the value using the second function
--   if it results in True, or the third function if it results in Fasle.
condModAVar :: AVar a -> (a -> Bool) -> (a -> a) -> (a -> a) -> IO (Either SomeException Bool)

-- | <a>swapAVar</a> takes a new value, puts it into the AVar, and returns
--   the old value.
swapAVar :: (AVar a) -> a -> IO (Either SomeException a)