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


-- | A fast implementation of synchronous channels with a CML-like API
--   
--   This is a short implementation of synchronous channels with choice,
--   based on the code described at
--   <a>http://chplib.wordpress.com/2010/03/04/choice-over-events-using-stm/</a>
@package sync
@version 0.1


-- | This library supports synchronous message-passing with choice in
--   Haskell. It is similar to the CML package for Haskell
--   (<a>http://hackage.haskell.org/package/cml</a>), and shares a similar
--   API. It avoids some of the problems the CML package has with choose on
--   GHC 6.12.1
--   (<a>http://www.haskell.org/pipermail/haskell-cafe/2010-March/074134.html</a>),
--   and also deliberately leaves out some of the features in the CML
--   package.
--   
--   The implementation is explained in this blog post:
--   <a>http://chplib.wordpress.com/2010/03/04/choice-over-events-using-stm/</a>.
--   The algorithm uses STM rather than spawning threads to implement
--   choice.
--   
--   At the moment the library is fairly unfeatured; if you want more
--   features I would suggest using my more powerful CHP library
--   (<a>http://hackage.haskell.org/package/chp</a>) -- but then I am
--   biased!
module Control.Concurrent.Sync

-- | A synchronisation that is yet to be executed (and that returns a
--   value). The functor instance allows you to modify the value after the
--   synchronisation has occurred.
data Event a

-- | A synchronous communication channel (i.e. the writer must wait until
--   the read is willing to read the value). Should only ever be used by
--   one writer and one reader -- the algorithm is not currently designed
--   for anything else.
data Channel a

-- | Creates an event that is the choice of the given list of events.
--   
--   If the list is a singleton this is equivalent to calling <a>head</a>.
--   If the list is empty, and you call <a>sync</a> on the resulting event,
--   it will block forever (or GHC will throw you an exception because of
--   it).
--   
--   You should not pass more than one event from each channel in the list
--   (nor combine two events that are themselves choices, such that you end
--   up combining more than one event from a channel) or undefined
--   behaviour will result.
choose :: [Event a] -> Event a

-- | Creates an event that represents sending the given value on the given
--   channel.
send :: Channel a -> a -> Event ()

-- | Creates an event that represents receiving a value from the given
--   channel.
recv :: Channel a -> Event a

-- | Creates a new communication channel.
newChannel :: IO (Channel a)

-- | Synchronises on an event. This blocks the thread until the Event can
--   occur. This may be a choice of several different events, via the
--   <a>choose</a> function.
sync :: Event a -> IO a
instance Functor Event
instance Eq (Channel a)
instance Eq Offer