Control.Concurrent.STM.TBMChan

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.

The TBMChan type

data TBMChan a

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

Instances

Typeable (* -> *) TBMChan

Creating TBMChans

newTBMChan :: Int -> STM (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.

newTBMChanIO :: Int -> IO (TBMChan a)

IO version of newTBMChan. This is useful for creating top-level TBMChans using unsafePerformIO, because using atomically inside unsafePerformIO isn't possible.

Reading from TBMChans

readTBMChan :: TBMChan a -> STM (Maybe 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.

tryReadTBMChan :: TBMChan a -> STM (Maybe (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.

peekTBMChan :: TBMChan a -> STM (Maybe a)

Get the next value from the TBMChan without removing it, retrying if the channel is empty.

tryPeekTBMChan :: TBMChan a -> STM (Maybe (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.

Writing to TBMChans

writeTBMChan :: TBMChan a -> a -> STM ()

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)

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

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

Closes the TBMChan, preventing any further writes.

Predicates

isClosedTBMChan :: TBMChan a -> STM Bool

Returns True if the supplied TBMChan has been closed.

isEmptyTBMChan :: TBMChan a -> STM Bool

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 Bool

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