| Copyright | Copyright (c) 2011--2013 wren ng thornton |
|---|---|
| License | BSD |
| Maintainer | wren@community.haskell.org |
| Stability | provisional |
| Portability | non-portable (GHC STM, DeriveDataTypeable) |
| Safe Haskell | Trustworthy |
| Language | Haskell98 |
Control.Concurrent.STM.TBChan
Contents
Description
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.
- data TBChan a
- newTBChan :: Int -> STM (TBChan a)
- newTBChanIO :: Int -> IO (TBChan a)
- readTBChan :: TBChan a -> STM a
- tryReadTBChan :: TBChan a -> STM (Maybe a)
- peekTBChan :: TBChan a -> STM a
- tryPeekTBChan :: TBChan a -> STM (Maybe a)
- writeTBChan :: TBChan a -> a -> STM ()
- tryWriteTBChan :: TBChan a -> a -> STM Bool
- unGetTBChan :: TBChan a -> a -> STM ()
- isEmptyTBChan :: TBChan a -> STM Bool
- isFullTBChan :: TBChan a -> STM Bool
- estimateFreeSlotsTBChan :: TBChan a -> STM Int
- freeSlotsTBChan :: TBChan a -> STM Int
The TBChan type
data TBChan a
TBChan is an abstract type representing a bounded FIFO
channel.
Creating TBChans
newTBChan :: Int -> STM (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.
newTBChanIO :: Int -> IO (TBChan a)
IO version of newTBChan. This is useful for creating
top-level TBChans using unsafePerformIO, because using
atomically inside unsafePerformIO isn't possible.
Reading from TBChans
readTBChan :: TBChan a -> STM a
Read the next value from the TBChan, retrying if the channel
is empty.
tryReadTBChan :: TBChan a -> STM (Maybe a)
A version of readTBChan which does not retry. Instead it
returns Nothing if no value is available.
peekTBChan :: TBChan a -> STM a
Get the next value from the TBChan without removing it,
retrying if the channel is empty.
tryPeekTBChan :: TBChan a -> STM (Maybe a)
A version of peekTBChan which does not retry. Instead it
returns Nothing if no value is available.
Writing to TBChans
writeTBChan :: TBChan a -> a -> STM ()
Write a value to a TBChan, retrying if the channel is full.
tryWriteTBChan :: TBChan a -> a -> STM Bool
A version of writeTBChan which does not retry. Returns True
if the value was successfully written, and False otherwise.
unGetTBChan :: TBChan a -> a -> STM ()
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.
Predicates
isEmptyTBChan :: TBChan a -> STM Bool
Returns True if the supplied TBChan is empty (i.e., has
no elements). N.B., a TBChan can be both ``empty'' and
``full'' at the same time, if the initial limit was non-positive.
isFullTBChan :: 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 ``empty'' 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
Other functionality
estimateFreeSlotsTBChan :: TBChan a -> STM Int
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.
freeSlotsTBChan :: 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.