Control.Concurrent.STM.TBMQueue

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. This variant incorporates ideas from Thomas M. DuBuisson's bounded-tqueue package in order to reduce contention between readers and writers.

Since: 2.0.0

The TBMQueue type

data TBMQueue a

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

Instances

Typeable1 TBMQueue

Creating TBMQueues

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

newTBMQueueIO :: Int -> IO (TBMQueue a)

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

Reading from TBMQueues

readTBMQueue :: TBMQueue a -> STM (Maybe 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.

tryReadTBMQueue :: TBMQueue a -> STM (Maybe (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.

peekTBMQueue :: TBMQueue a -> STM (Maybe a)

Get the next value from the TBMQueue without removing it, retrying if the queue is empty.

tryPeekTBMQueue :: TBMQueue a -> STM (Maybe (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.

Writing to TBMQueues

writeTBMQueue :: TBMQueue a -> a -> STM ()

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.

tryWriteTBMQueue :: TBMQueue a -> a -> STM (Maybe Bool)

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

unGetTBMQueue :: TBMQueue 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 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.

Closing TBMQueues

closeTBMQueue :: TBMQueue a -> STM ()

Closes the TBMQueue, preventing any further writes.

Predicates

isClosedTBMQueue :: TBMQueue a -> STM Bool

Returns True if the supplied TBMQueue has been closed.

isEmptyTBMQueue :: TBMQueue a -> STM Bool

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

isFullTBMQueue :: 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 `empty' 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

Other functionality

estimateFreeSlotsTBMQueue :: TBMQueue 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 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.

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