Control.Concurrent.STM.TMChunkedQueue

A version of Control.Concurrent.STM.TQueue where the queue is closeable and allows complete draining. This makes it possible to chunk items based on a timeout or a settle period. This is useful when items/requests arriving through the queue are too granular and have to be combined, while retaining responsiveness.

Some capabilities of TQueue are missing (such as unget) due to design tradeoffs.

Since: 0.1.0

The TMChunkedQueue type

data TMChunkedQueue a

TMChunkedQueue is an abstract type representing a closeable, drainable FIFO queue.

Instances

Typeable1 TMChunkedQueue

data ChunkedQueue a

Abstract type representing a chunked queue. Acts as API for drainining queues.

Instances

Monoid (ChunkedQueue a)

consumeQueue :: ChunkedQueue a -> [a]

Consume a ChunkedQueue into a list

Creating TMChunkedQueues

newTMChunkedQueue :: STM (TMChunkedQueue a)

Build and returns a new instance of TMChunkedQueue

newTMChunkedQueueIO :: IO (TMChunkedQueue a)

IO version of newTMChunkedQueue

Draining TMChunkedQueues

drainTMChunkedQueue :: TMChunkedQueue a -> STM (Maybe (ChunkedQueue a))

Drain everything contained in the TMChunkedQueue, but block if it is empty. Corollary: never returns empty queue.

• Closed, Empty - Nothing * Closed, Non-Empty - Just [...] * Open, Empty - Blocks * Open, Non-Empty - Just [...]

tryDrainTMChunkedQueue :: TMChunkedQueue a -> STM (Maybe (ChunkedQueue a))

Drain everything contained in the TMChunkedQueue. Doesn't block.

• Closed, Empty - Nothing * Closed, Non-Empty - Just [...] * Open, Empty - Just [] * Open, Non-Empty - Just [...]

Writing to TMChunkedQueues

writeTMChunkedQueue :: TMChunkedQueue a -> a -> STM ()

Write a value to a TMChunkedQueue

writeManyTMChunkedQueue :: TMChunkedQueue a -> [a] -> STM ()

Write many values to a TMChunkedQueue

Closing TMChunkedQueues

closeTMChunkedQueue :: TMChunkedQueue a -> STM ()

Closes the TMQueue, preventing any further writes.

Predicates

isEmptyTMChunkedQueue :: TMChunkedQueue a -> STM Bool

Returns True if the supplied TMChunkedQueue is empty.

isClosedTMChunkedQueue :: TMChunkedQueue a -> STM Bool

Returns True if the supplied TMChunkedQueue has been closed.

Chunked operations

drainAndSettleTMChunkedQueue

Arguments

:: Int

settle period in microseconds

-> TMChunkedQueue a

-> IO (Maybe (ChunkedQueue a))

Keep draining the queue until no more items are seen for at least the given timeout period. Blocks if the queue is empty to begin with, and starts timing after the first value appears in the queue.

drainWithTimeoutTMChunkedQueue

Arguments

:: Int

timeout in microseconds

-> TMChunkedQueue a

-> IO (Maybe (ChunkedQueue a))

Keep draining the queue for at least the specified time period. Blocks if the queue is empty to begin with, and starts timing as soon as the first value appears in the queue.