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

-- | Additional types of channels for STM.
--   
--   Additional types of channels for STM.
@package stm-chans
@version 3.0.0.4

-- | A version of Control.Concurrent.STM.TQueue where the queue is
--   closeable. This is similar to a TQueue (Maybe a) with a
--   monotonicity guarantee that once there's a Nothing there will
--   always be Nothing.
--   
--   Since: 2.0.0
module Control.Concurrent.STM.TMQueue

-- | TMQueue is an abstract type representing a closeable FIFO
--   queue.
data TMQueue a

-- | Build and returns a new instance of TMQueue.
newTMQueue :: STM (TMQueue a)

-- | IO version of newTMQueue. This is useful for creating
--   top-level TMQueues using unsafePerformIO, because
--   using atomically inside unsafePerformIO isn't possible.
newTMQueueIO :: IO (TMQueue a)

-- | Read the next value from the TMQueue, retrying if the queue
--   is empty (and not closed). We return Nothing immediately if
--   the queue is closed and empty.
readTMQueue :: TMQueue a -> STM (Maybe a)

-- | A version of readTMQueue which does not retry. Instead it
--   returns Just Nothing if the queue is open but no value is
--   available; it still returns Nothing if the queue is closed
--   and empty.
tryReadTMQueue :: TMQueue a -> STM (Maybe (Maybe a))

-- | Get the next value from the TMQueue without removing it,
--   retrying if the queue is empty.
peekTMQueue :: TMQueue a -> STM (Maybe a)

-- | A version of peekTMQueue which does not retry. Instead it
--   returns Just Nothing if the queue is open but no value is
--   available; it still returns Nothing if the queue is closed
--   and empty.
tryPeekTMQueue :: TMQueue a -> STM (Maybe (Maybe a))

-- | Write a value to a TMQueue. If the queue is closed then the
--   value is silently discarded. Use isClosedTMQueue to determine
--   if the queue is closed before writing, as needed.
writeTMQueue :: TMQueue a -> a -> STM ()

-- | Put a data item back onto a queue, where it will be the next item
--   read. If the queue is closed then the value is silently discarded; you
--   can use peekTMQueue to circumvent this in certain
--   circumstances.
unGetTMQueue :: TMQueue a -> a -> STM ()

-- | Closes the TMQueue, preventing any further writes.
closeTMQueue :: TMQueue a -> STM ()

-- | Returns True if the supplied TMQueue has been
--   closed.
isClosedTMQueue :: TMQueue a -> STM Bool

-- | Returns True if the supplied TMQueue is empty.
isEmptyTMQueue :: TMQueue a -> STM Bool

-- | A version of Control.Concurrent.STM.TChan where the queue is
--   closeable. This is similar to a TChan (Maybe a) with a
--   monotonicity guarantee that once there's a Nothing there will
--   always be Nothing.
module Control.Concurrent.STM.TMChan

-- | TMChan is an abstract type representing a closeable FIFO
--   channel.
data TMChan a

-- | Build and returns a new instance of TMChan.
newTMChan :: STM (TMChan a)

-- | IO version of newTMChan. This is useful for creating
--   top-level TMChans using unsafePerformIO, because using
--   atomically inside unsafePerformIO isn't possible.
newTMChanIO :: IO (TMChan a)

-- | Duplicate a TMChan: the duplicate channel begins empty, but
--   data written to either channel from then on will be available from
--   both, and closing one copy will close them all. Hence this creates a
--   kind of broadcast channel, where data written by anyone is seen by
--   everyone else.
dupTMChan :: TMChan a -> STM (TMChan a)

-- | Like newBroadcastTChan.
--   
--   Since: 2.1.0
newBroadcastTMChan :: STM (TMChan a)

-- | IO version of newBroadcastTMChan.
--   
--   Since: 2.1.0
newBroadcastTMChanIO :: IO (TMChan a)

-- | Read the next value from the TMChan, retrying if the channel
--   is empty (and not closed). We return Nothing immediately if
--   the channel is closed and empty.
readTMChan :: TMChan a -> STM (Maybe a)

-- | A version of readTMChan which does not retry. Instead it
--   returns Just Nothing if the channel is open but no value is
--   available; it still returns Nothing if the channel is closed
--   and empty.
tryReadTMChan :: TMChan a -> STM (Maybe (Maybe a))

-- | Get the next value from the TMChan without removing it,
--   retrying if the channel is empty.
peekTMChan :: TMChan a -> STM (Maybe a)

-- | A version of peekTMChan which does not retry. Instead it
--   returns Just Nothing if the channel is open but no value is
--   available; it still returns Nothing if the channel is closed
--   and empty.
tryPeekTMChan :: TMChan a -> STM (Maybe (Maybe a))

-- | Write a value to a TMChan. If the channel is closed then the
--   value is silently discarded. Use isClosedTMChan to determine if
--   the channel is closed before writing, as needed.
writeTMChan :: TMChan a -> a -> STM ()

-- | Put a data item back onto a channel, where it will be the next item
--   read. If the channel is closed then the value is silently discarded;
--   you can use peekTMChan to circumvent this in certain
--   circumstances.
unGetTMChan :: TMChan a -> a -> STM ()

-- | Closes the TMChan, preventing any further writes.
closeTMChan :: TMChan a -> STM ()

-- | Returns True if the supplied TMChan has been closed.
isClosedTMChan :: TMChan a -> STM Bool

-- | Returns True if the supplied TMChan is empty.
isEmptyTMChan :: TMChan a -> STM Bool

-- | A version of Control.Concurrent.STM.TQueue where the queue is
--   bounded in length and closeable. This combines the abilities of
--   Control.Concurrent.STM.TBQueue and
--   Control.Concurrent.STM.TMQueue.
--   
--   Since: 2.0.0
module Control.Concurrent.STM.TBMQueue

-- | TBMQueue is an abstract type representing a bounded closeable
--   FIFO queue.
data TBMQueue a

-- | Build and returns a new instance of TBMQueue with the given
--   capacity. N.B., we do not verify the capacity is positive, but
--   if it is non-positive then writeTBMQueue will always retry and
--   isFullTBMQueue will always be true.
newTBMQueue :: Int -> STM (TBMQueue a)

-- | IO version of newTBMQueue. This is useful for creating
--   top-level TBMQueues using unsafePerformIO, because
--   using atomically inside unsafePerformIO isn't possible.
newTBMQueueIO :: Int -> IO (TBMQueue a)

-- | Read the next value from the TBMQueue, retrying if the queue
--   is empty (and not closed). We return Nothing immediately if
--   the queue is closed and empty.
readTBMQueue :: TBMQueue a -> STM (Maybe a)

-- | A version of readTBMQueue which does not retry. Instead it
--   returns Just Nothing if the queue is open but no value is
--   available; it still returns Nothing if the queue is closed
--   and empty.
tryReadTBMQueue :: TBMQueue a -> STM (Maybe (Maybe a))

-- | Get the next value from the TBMQueue without removing it,
--   retrying if the queue is empty.
peekTBMQueue :: TBMQueue a -> STM (Maybe a)

-- | A version of peekTBMQueue which does not retry. Instead it
--   returns Just Nothing if the queue is open but no value is
--   available; it still returns Nothing if the queue is closed
--   and empty.
tryPeekTBMQueue :: TBMQueue a -> STM (Maybe (Maybe a))

-- | Write a value to a TBMQueue, retrying if the queue is full.
--   If the queue is closed then the value is silently discarded. Use
--   isClosedTBMQueue to determine if the queue is closed before
--   writing, as needed.
writeTBMQueue :: TBMQueue a -> a -> STM ()

-- | A version of writeTBMQueue which does not retry. Returns
--   Just True if the value was successfully written, Just
--   False if it could not be written (but the queue was open), and
--   Nothing if it was discarded (i.e., the queue was closed).
tryWriteTBMQueue :: TBMQueue a -> a -> STM (Maybe Bool)

-- | Put a data item back onto a queue, where it will be the next item
--   read. If the queue is closed then the value is silently discarded; you
--   can use peekTBMQueue to circumvent this in certain
--   circumstances. N.B., this could allow the queue to temporarily
--   become longer than the specified limit, which is necessary to ensure
--   that the item is indeed the next one read.
unGetTBMQueue :: TBMQueue a -> a -> STM ()

-- | Closes the TBMQueue, preventing any further writes.
closeTBMQueue :: TBMQueue a -> STM ()

-- | Returns True if the supplied TBMQueue has been
--   closed.
isClosedTBMQueue :: TBMQueue a -> STM Bool

-- | Returns True if the supplied TBMQueue is empty
--   (i.e., has no elements). N.B., a TBMQueue can be both
--   `<tt>empty'</tt> and `full' at the same time, if the initial
--   limit was non-positive.
isEmptyTBMQueue :: TBMQueue a -> STM Bool

-- | Returns True if the supplied TBMQueue is full (i.e.,
--   is over its limit). N.B., a TBMQueue can be both
--   `<tt>empty'</tt> and `full' at the same time, if the initial
--   limit was non-positive. N.B., a TBMQueue may still be
--   full after reading, if unGetTBMQueue was used to go over the
--   initial limit.
--   
--   This is equivalent to: liftM (<= 0)
--   estimateFreeSlotsTBMQueue
isFullTBMQueue :: TBMQueue a -> STM Bool

-- | Estimate the number of free slots. If the result is positive, then
--   it's a minimum bound; if it's non-positive then it's exact. It will
--   only be negative if the initial limit was negative or if
--   unGetTBMQueue was used to go over the initial limit.
--   
--   This function always contends with writers, but only contends with
--   readers when it has to; compare against freeSlotsTBMQueue.
estimateFreeSlotsTBMQueue :: TBMQueue a -> STM Int

-- | Return the exact number of free slots. The result can be negative if
--   the initial limit was negative or if unGetTBMQueue was used to
--   go over the initial limit.
--   
--   This function always contends with both readers and writers; compare
--   against estimateFreeSlotsTBMQueue.
freeSlotsTBMQueue :: TBMQueue a -> STM Int

-- | A version of Control.Concurrent.STM.TChan where the queue is
--   bounded in length and closeable. This combines the abilities of
--   Control.Concurrent.STM.TBChan and
--   Control.Concurrent.STM.TMChan. This variant incorporates ideas
--   from Thomas M. DuBuisson's bounded-tchan package in order to
--   reduce contention between readers and writers.
module Control.Concurrent.STM.TBMChan

-- | TBMChan is an abstract type representing a bounded closeable
--   FIFO channel.
data TBMChan a

-- | Build and returns a new instance of TBMChan with the given
--   capacity. N.B., we do not verify the capacity is positive, but
--   if it is non-positive then writeTBMChan will always retry and
--   isFullTBMChan will always be true.
newTBMChan :: Int -> STM (TBMChan a)

-- | IO version of newTBMChan. This is useful for creating
--   top-level TBMChans using unsafePerformIO, because
--   using atomically inside unsafePerformIO isn't possible.
newTBMChanIO :: Int -> IO (TBMChan a)

-- | Read the next value from the TBMChan, retrying if the channel
--   is empty (and not closed). We return Nothing immediately if
--   the channel is closed and empty.
readTBMChan :: TBMChan a -> STM (Maybe a)

-- | A version of readTBMChan which does not retry. Instead it
--   returns Just Nothing if the channel is open but no value is
--   available; it still returns Nothing if the channel is closed
--   and empty.
tryReadTBMChan :: TBMChan a -> STM (Maybe (Maybe a))

-- | Get the next value from the TBMChan without removing it,
--   retrying if the channel is empty.
peekTBMChan :: TBMChan a -> STM (Maybe a)

-- | A version of peekTBMChan which does not retry. Instead it
--   returns Just Nothing if the channel is open but no value is
--   available; it still returns Nothing if the channel is closed
--   and empty.
tryPeekTBMChan :: TBMChan a -> STM (Maybe (Maybe a))

-- | Write a value to a TBMChan, retrying if the channel is full.
--   If the channel is closed then the value is silently discarded. Use
--   isClosedTBMChan to determine if the channel is closed before
--   writing, as needed.
writeTBMChan :: TBMChan a -> a -> STM ()

-- | A version of writeTBMChan which does not retry. Returns
--   Just True if the value was successfully written, Just
--   False if it could not be written (but the channel was open), and
--   Nothing if it was discarded (i.e., the channel was closed).
tryWriteTBMChan :: TBMChan a -> a -> STM (Maybe Bool)

-- | Put a data item back onto a channel, where it will be the next item
--   read. If the channel is closed then the value is silently discarded;
--   you can use peekTBMChan to circumvent this in certain
--   circumstances. N.B., this could allow the channel to
--   temporarily become longer than the specified limit, which is necessary
--   to ensure that the item is indeed the next one read.
unGetTBMChan :: TBMChan a -> a -> STM ()

-- | Closes the TBMChan, preventing any further writes.
closeTBMChan :: TBMChan a -> STM ()

-- | Returns True if the supplied TBMChan has been
--   closed.
isClosedTBMChan :: TBMChan a -> STM Bool

-- | Returns True if the supplied TBMChan is empty (i.e.,
--   has no elements). N.B., a TBMChan can be both
--   `<tt>empty'</tt> and `full' at the same time, if the initial
--   limit was non-positive.
isEmptyTBMChan :: TBMChan a -> STM Bool

-- | Returns True if the supplied TBMChan is full (i.e.,
--   is over its limit). N.B., a TBMChan can be both
--   `<tt>empty'</tt> and `full' at the same time, if the initial
--   limit was non-positive. N.B., a TBMChan may still be
--   full after reading, if unGetTBMChan was used to go over the
--   initial limit.
--   
--   This is equivalent to: liftM (<= 0)
--   estimateFreeSlotsTBMChan
isFullTBMChan :: TBMChan a -> STM Bool

-- | Estimate the number of free slots. If the result is positive, then
--   it's a minimum bound; if it's non-positive then it's exact. It will
--   only be negative if the initial limit was negative or if
--   unGetTBMChan was used to go over the initial limit.
--   
--   This function always contends with writers, but only contends with
--   readers when it has to; compare against freeSlotsTBMChan.
estimateFreeSlotsTBMChan :: TBMChan a -> STM Int

-- | Return the exact number of free slots. The result can be negative if
--   the initial limit was negative or if unGetTBMChan was used to
--   go over the initial limit.
--   
--   This function always contends with both readers and writers; compare
--   against estimateFreeSlotsTBMChan.
freeSlotsTBMChan :: TBMChan a -> STM Int

-- | A version of Control.Concurrent.STM.TChan where the queue is
--   bounded in length. This variant incorporates ideas from Thomas M.
--   DuBuisson's bounded-tchan package in order to reduce
--   contention between readers and writers.
module Control.Concurrent.STM.TBChan

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

-- | Build and returns a new instance of TBChan with the given
--   capacity. N.B., we do not verify the capacity is positive, but
--   if it is non-positive then writeTBChan will always retry and
--   isFullTBChan will always be true.
newTBChan :: Int -> STM (TBChan a)

-- | IO version of newTBChan. This is useful for creating
--   top-level TBChans using unsafePerformIO, because using
--   atomically inside unsafePerformIO isn't possible.
newTBChanIO :: Int -> IO (TBChan a)

-- | Read the next value from the TBChan, retrying if the channel
--   is empty.
readTBChan :: TBChan a -> STM a

-- | A version of readTBChan which does not retry. Instead it
--   returns Nothing if no value is available.
tryReadTBChan :: TBChan a -> STM (Maybe a)

-- | Get the next value from the TBChan without removing it,
--   retrying if the channel is empty.
peekTBChan :: TBChan a -> STM a

-- | A version of peekTBChan which does not retry. Instead it
--   returns Nothing if no value is available.
tryPeekTBChan :: TBChan a -> STM (Maybe a)

-- | Write a value to a TBChan, retrying if the channel is full.
writeTBChan :: TBChan a -> a -> STM ()

-- | A version of writeTBChan which does not retry. Returns
--   True if the value was successfully written, and
--   False otherwise.
tryWriteTBChan :: TBChan a -> a -> STM Bool

-- | Put a data item back onto a channel, where it will be the next item
--   read. N.B., this could allow the channel to temporarily become
--   longer than the specified limit, which is necessary to ensure that the
--   item is indeed the next one read.
unGetTBChan :: TBChan a -> a -> STM ()

-- | Returns True if the supplied TBChan is empty (i.e.,
--   has no elements). N.B., a TBChan can be both
--   `<tt>empty'</tt> and `full' at the same time, if the initial
--   limit was non-positive.
isEmptyTBChan :: TBChan a -> STM Bool

-- | Returns True if the supplied TBChan is full (i.e.,
--   is over its limit). N.B., a TBChan can be both
--   `<tt>empty'</tt> and `full' at the same time, if the initial
--   limit was non-positive. N.B., a TBChan may still be
--   full after reading, if unGetTBChan was used to go over the
--   initial limit.
--   
--   This is equivalent to: liftM (<= 0)
--   estimateFreeSlotsTBMChan
isFullTBChan :: TBChan a -> STM Bool

-- | Estimate the number of free slots. If the result is positive, then
--   it's a minimum bound; if it's non-positive then it's exact. It will
--   only be negative if the initial limit was negative or if
--   unGetTBChan was used to go over the initial limit.
--   
--   This function always contends with writers, but only contends with
--   readers when it has to; compare against freeSlotsTBChan.
estimateFreeSlotsTBChan :: TBChan a -> STM Int

-- | Return the exact number of free slots. The result can be negative if
--   the initial limit was negative or if unGetTBChan was used to go
--   over the initial limit.
--   
--   This function always contends with both readers and writers; compare
--   against estimateFreeSlotsTBChan.
freeSlotsTBChan :: TBChan a -> STM Int
