-- 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. There is also an
--   unsafe interface through Data.AVar.Unsafe, which will throw any errors
--   encountered while modifying the variable.
@package AVar
@version 0.0.4


-- | The guts of how AVars work.
module Data.AVar.Internal

-- | <a>AVar</a>s are the means through which 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
AVar :: (Chan (Transaction a)) -> 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

-- | Just modifies the variable (unless an exception occurs)
JustMod :: (a -> a) -> 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)


-- | Data.AVar.Unsafe has a similar interface to Data.AVar, but instead of
--   letting the user handle exceptions from Eithers, it will throw
--   exceptions caught by the variable.
module Data.AVar.Unsafe

-- | <a>AVar</a>s are the means through which 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
data Result
OK :: Result

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

-- | <a>putAVar</a> replaces the currect value in the variable with the
--   given x
putAVar :: AVar a -> a -> IO ()

-- | <a>modAVar</a> takes a function from a to a, and modifies the
--   variable. It will throw any exceptions caught by the variable when
--   applying the function.
modAVar :: AVar a -> (a -> a) -> IO ()

-- | <a>modAVar'</a> is like modAVar, but it modifies the variable, along
--   with returning a result of type b. It also throws any errors caugh by
--   the variable.
modAVar' :: AVar a -> (a -> (a, b)) -> IO b

-- | <a>justModAVar</a> will attempt to run the given function on the
--   variable. It does not report back on its sucess or failure, and if the
--   function produces an exception, the variable is left unchanged. It
--   should be used when you just want to modify the variable, and keep
--   running, without waiting for the action to complete.
justModAVar :: AVar a -> (a -> a) -> IO ()

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

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


-- | 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 guaranteed
--   to happen. They are designed to cope with exceptions thrown by any
--   modifying functions; any exception thrown during a transaction will
--   either be passed back to the caller or ignored, and the variable keeps
--   on running.
--   
--   They are handy for applications like keeping track of resources by
--   incrementing and decrementing the variable. They should not be used in
--   a way which you would read the variable, then modify it based on the
--   result recieved, but rather using the provided functions. If this was
--   not done, the variable's value is very likely to have changed in the
--   mean time.
--   
--   If you're after a more unsafe interface to AVars, see
--   Data.AVar.Unsafe, which will throw the errors returned fromt he
--   variable.
module Data.AVar

-- | <a>AVar</a>s are the means through which 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>putAVar</a> replaces the currect value in the variable with the
--   given x
putAVar :: AVar 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>justModAVar</a> will attempt to run the given function on the
--   variable. It does not report back on its sucess or failure, and if the
--   function produces an exception, the variable is left unchanged. It
--   should be used when you just want to modify the variable, and keep
--   running, without waiting for the action to complete.
justModAVar :: AVar a -> (a -> a) -> IO ()

-- | <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)