-- 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.1.0

-- | Implements bounded channels. These channels differ from normal
--   Chans 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
--   Control.Concurrent.Chan except unGetChan and
--   dupChan, 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

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

-- | newBoundedChan n returns a channel than can contain no more
--   than n 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 ()

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

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

-- | Deprecated: This isEmptyChan can block, no non-blocking substitute
--   yet 
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 ()
