Portability | non-portable (GHC STM, DeriveDataTypeable) |
---|---|
Stability | provisional |
Maintainer | wren@community.haskell.org |
Safe Haskell | Trustworthy |
Control.Concurrent.STM.TBMChan
Contents
Description
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.
- data TBMChan a
- newTBMChan :: Int -> STM (TBMChan a)
- newTBMChanIO :: Int -> IO (TBMChan a)
- readTBMChan :: TBMChan a -> STM (Maybe a)
- tryReadTBMChan :: TBMChan a -> STM (Maybe (Maybe a))
- peekTBMChan :: TBMChan a -> STM (Maybe a)
- tryPeekTBMChan :: TBMChan a -> STM (Maybe (Maybe a))
- writeTBMChan :: TBMChan a -> a -> STM ()
- tryWriteTBMChan :: TBMChan a -> a -> STM (Maybe Bool)
- unGetTBMChan :: TBMChan a -> a -> STM ()
- closeTBMChan :: TBMChan a -> STM ()
- isClosedTBMChan :: TBMChan a -> STM Bool
- isEmptyTBMChan :: TBMChan a -> STM Bool
- isFullTBMChan :: TBMChan a -> STM Bool
- estimateFreeSlotsTBMChan :: TBMChan a -> STM Int
- freeSlotsTBMChan :: TBMChan a -> STM Int
The TBMChan type
TBMChan
is an abstract type representing a bounded closeable
FIFO channel.
Creating TBMChans
newTBMChan :: Int -> STM (TBMChan a)Source
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.
newTBMChanIO :: Int -> IO (TBMChan a)Source
IO
version of newTBMChan
. This is useful for creating
top-level TBMChan
s using unsafePerformIO
, because using
atomically
inside unsafePerformIO
isn't possible.
Reading from TBMChans
readTBMChan :: TBMChan a -> STM (Maybe a)Source
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.
tryReadTBMChan :: TBMChan a -> STM (Maybe (Maybe a))Source
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.
peekTBMChan :: TBMChan a -> STM (Maybe a)Source
Get the next value from the TBMChan
without removing it,
retrying if the channel is empty.
tryPeekTBMChan :: TBMChan a -> STM (Maybe (Maybe a))Source
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.
Writing to TBMChans
writeTBMChan :: TBMChan a -> a -> STM ()Source
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.
tryWriteTBMChan :: TBMChan a -> a -> STM (Maybe Bool)Source
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).
unGetTBMChan :: TBMChan a -> a -> STM ()Source
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.
Closing TBMChans
closeTBMChan :: TBMChan a -> STM ()Source
Closes the TBMChan
, preventing any further writes.
Predicates
isClosedTBMChan :: TBMChan a -> STM BoolSource
Returns True
if the supplied TBMChan
has been closed.
isEmptyTBMChan :: TBMChan a -> STM BoolSource
Returns True
if the supplied TBMChan
is empty (i.e., has
no elements). N.B., a TBMChan
can be both `empty'
and
`full'
at the same time, if the initial limit was non-positive.
isFullTBMChan :: TBMChan a -> STM BoolSource
Returns True
if the supplied TBMChan
is full (i.e., is
over its limit). N.B., a TBMChan
can be both `empty'
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
Other functionality
estimateFreeSlotsTBMChan :: TBMChan a -> STM IntSource
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
.
freeSlotsTBMChan :: TBMChan a -> STM IntSource
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
.