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


-- | Implementation of bounded channels.
--   
--   This library introduces BoundedChan. BoundedChans differ from Chans in
--   that they are guaranteed to contain no more than a certain number of
--   elements.
@package BoundedChan
@version 1.0.3.0


-- | Implements bounded channels. These channels differ from normal
--   <tt>Chan</tt>s in that they are guaranteed to contain no more than a
--   certain number of elements. This is ideal when you may be writing to a
--   channel faster than you are able to read from it.
--   
--   This module supports all the functions of
--   <a>Control.Concurrent.Chan</a> except <tt>unGetChan</tt> and
--   <tt>dupChan</tt>, which are not supported for bounded channels.
--   
--   Extra consitency: This version enforces that if thread Alice writes e1
--   followed by e2 then e1 will be returned by readChan before e2.
--   Conversely, if thead Bob reads e1 followed by e2 then it was true that
--   writeChan e1 preceded writeChan e2.
--   
--   Previous versions did not enforce this consistency: if writeChan were
--   preempted between putMVars or killThread arrived between putMVars then
--   it can fail. Similarly it might fail if readChan were stopped after
--   putMVar and before the second takeMVar. An unlucky pattern of several
--   such deaths might actually break the invariants of the array in an
--   unrecoverable way causing all future reads and writes to block.
module Control.Concurrent.BoundedChan

-- | <a>BoundedChan</a> is an abstract data type representing a bounded
--   channel.
data BoundedChan a

-- | <tt>newBoundedChan n</tt> returns a channel than can contain no more
--   than <tt>n</tt> elements.
newBoundedChan :: Int -> IO (BoundedChan a)

-- | Write an element to the channel. If the channel is full, this routine
--   will block until it is able to write. Blockers wait in a fair FIFO
--   queue.
writeChan :: BoundedChan a -> a -> IO ()

-- | A variant of <a>writeChan</a> which, instead of blocking when the
--   channel is full, simply aborts and does not write the element. Note
--   that this routine can still block while waiting for write access to
--   the channel.
tryWriteChan :: BoundedChan a -> a -> IO Bool

-- | Read an element from the channel. If the channel is empty, this
--   routine will block until it is able to read. Blockers wait in a fair
--   FIFO queue.
readChan :: BoundedChan a -> IO a

-- | A variant of <a>readChan</a> which, instead of blocking when the
--   channel is empty, immediately returns <a>Nothing</a>. Otherwise,
--   <a>tryReadChan</a> returns <tt><a>Just</a> a</tt> where <tt>a</tt> is
--   the element read from the channel. Note that this routine can still
--   block while waiting for read access to the channel.
tryReadChan :: BoundedChan a -> IO (Maybe a)

-- | DANGER: This may block on an empty channel if there is already a
--   blocked reader. Returns <a>True</a> if the supplied channel is empty.
--   
--   DEPRECATED

-- | <i>Deprecated: This isEmptyChan can block, no non-blocking substitute
--   yet </i>
isEmptyChan :: BoundedChan a -> IO Bool

-- | Return a lazy list representing the contents of the supplied channel.
--   Competing readers might steal from this list.
getChanContents :: BoundedChan a -> IO [a]

-- | Write a list of elements to the channel. If the channel becomes full,
--   this routine will block until it is able to write. Competing writers
--   may interleave with this one.
writeList2Chan :: BoundedChan a -> [a] -> IO ()