libghc-stm-chans-doc 3.0.0.4-5build1 / usr / share / doc / libghc-stm-chans-doc / html / stm-chans.txt

-- 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 <a>Control.Concurrent.STM.TQueue</a> where the queue is
--   closeable. This is similar to a <tt>TQueue (Maybe a)</tt> with a
--   monotonicity guarantee that once there's a <tt>Nothing</tt> there will
--   always be <tt>Nothing</tt>.
--   
--   <i>Since: 2.0.0</i>
module Control.Concurrent.STM.TMQueue

-- | <tt>TMQueue</tt> is an abstract type representing a closeable FIFO
--   queue.
data TMQueue a

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

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

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

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

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

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

-- | Write a value to a <tt>TMQueue</tt>. If the queue is closed then the
--   value is silently discarded. Use <a>isClosedTMQueue</a> 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 <a>peekTMQueue</a> to circumvent this in certain
--   circumstances.
unGetTMQueue :: TMQueue a -> a -> STM ()

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

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

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


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

-- | <tt>TMChan</tt> is an abstract type representing a closeable FIFO
--   channel.
data TMChan a

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

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

-- | Duplicate a <tt>TMChan</tt>: 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 <a>newBroadcastTChan</a>.
--   
--   <i>Since: 2.1.0</i>
newBroadcastTMChan :: STM (TMChan a)

-- | <tt>IO</tt> version of <a>newBroadcastTMChan</a>.
--   
--   <i>Since: 2.1.0</i>
newBroadcastTMChanIO :: IO (TMChan a)

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

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

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

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

-- | Write a value to a <tt>TMChan</tt>. If the channel is closed then the
--   value is silently discarded. Use <a>isClosedTMChan</a> 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 <a>peekTMChan</a> to circumvent this in certain
--   circumstances.
unGetTMChan :: TMChan a -> a -> STM ()

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

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

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


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

-- | <tt>TBMQueue</tt> is an abstract type representing a bounded closeable
--   FIFO queue.
data TBMQueue a

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

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

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

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

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

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

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

-- | A version of <a>writeTBMQueue</a> which does not retry. Returns
--   <tt>Just True</tt> if the value was successfully written, <tt>Just
--   False</tt> if it could not be written (but the queue was open), and
--   <tt>Nothing</tt> 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 <a>peekTBMQueue</a> to circumvent this in certain
--   circumstances. <i>N.B.</i>, 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 <tt>TBMQueue</tt>, preventing any further writes.
closeTBMQueue :: TBMQueue a -> STM ()

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

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

-- | Returns <tt>True</tt> if the supplied <tt>TBMQueue</tt> is full (i.e.,
--   is over its limit). <i>N.B.</i>, a <tt>TBMQueue</tt> can be both
--   `<tt>empty'</tt> and `<tt>full'</tt> at the same time, if the initial
--   limit was non-positive. <i>N.B.</i>, a <tt>TBMQueue</tt> may still be
--   full after reading, if <a>unGetTBMQueue</a> was used to go over the
--   initial limit.
--   
--   This is equivalent to: <tt>liftM (&lt;= 0)
--   estimateFreeSlotsTBMQueue</tt>
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
--   <a>unGetTBMQueue</a> 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 <a>freeSlotsTBMQueue</a>.
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 <a>unGetTBMQueue</a> was used to
--   go over the initial limit.
--   
--   This function always contends with both readers and writers; compare
--   against <a>estimateFreeSlotsTBMQueue</a>.
freeSlotsTBMQueue :: TBMQueue a -> STM Int


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

-- | <tt>TBMChan</tt> is an abstract type representing a bounded closeable
--   FIFO channel.
data TBMChan a

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

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

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

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

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

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

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

-- | A version of <a>writeTBMChan</a> which does not retry. Returns
--   <tt>Just True</tt> if the value was successfully written, <tt>Just
--   False</tt> if it could not be written (but the channel was open), and
--   <tt>Nothing</tt> 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 <a>peekTBMChan</a> to circumvent this in certain
--   circumstances. <i>N.B.</i>, 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 <tt>TBMChan</tt>, preventing any further writes.
closeTBMChan :: TBMChan a -> STM ()

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

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

-- | Returns <tt>True</tt> if the supplied <tt>TBMChan</tt> is full (i.e.,
--   is over its limit). <i>N.B.</i>, a <tt>TBMChan</tt> can be both
--   `<tt>empty'</tt> and `<tt>full'</tt> at the same time, if the initial
--   limit was non-positive. <i>N.B.</i>, a <tt>TBMChan</tt> may still be
--   full after reading, if <a>unGetTBMChan</a> was used to go over the
--   initial limit.
--   
--   This is equivalent to: <tt>liftM (&lt;= 0)
--   estimateFreeSlotsTBMChan</tt>
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
--   <a>unGetTBMChan</a> 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 <a>freeSlotsTBMChan</a>.
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 <a>unGetTBMChan</a> was used to
--   go over the initial limit.
--   
--   This function always contends with both readers and writers; compare
--   against <a>estimateFreeSlotsTBMChan</a>.
freeSlotsTBMChan :: TBMChan a -> STM Int


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

-- | <tt>TBChan</tt> is an abstract type representing a bounded FIFO
--   channel.
data TBChan a

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

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

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

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

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

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

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

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

-- | Put a data item back onto a channel, where it will be the next item
--   read. <i>N.B.</i>, 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 <tt>True</tt> if the supplied <tt>TBChan</tt> is empty (i.e.,
--   has no elements). <i>N.B.</i>, a <tt>TBChan</tt> can be both
--   `<tt>empty'</tt> and `<tt>full'</tt> at the same time, if the initial
--   limit was non-positive.
isEmptyTBChan :: TBChan a -> STM Bool

-- | Returns <tt>True</tt> if the supplied <tt>TBChan</tt> is full (i.e.,
--   is over its limit). <i>N.B.</i>, a <tt>TBChan</tt> can be both
--   `<tt>empty'</tt> and `<tt>full'</tt> at the same time, if the initial
--   limit was non-positive. <i>N.B.</i>, a <tt>TBChan</tt> may still be
--   full after reading, if <a>unGetTBChan</a> was used to go over the
--   initial limit.
--   
--   This is equivalent to: <tt>liftM (&lt;= 0)
--   estimateFreeSlotsTBMChan</tt>
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
--   <a>unGetTBChan</a> 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 <a>freeSlotsTBChan</a>.
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 <a>unGetTBChan</a> was used to go
--   over the initial limit.
--   
--   This function always contends with both readers and writers; compare
--   against <a>estimateFreeSlotsTBChan</a>.
freeSlotsTBChan :: TBChan a -> STM Int