rolling-queue-0.1: Bounded channel for STM that discards old entries when full

PortabilityRequires STM
Safe HaskellSafe-Infered




This module is usually imported qualified:

import Data.STM.RollingQueue (RollingQueue)
import qualified Data.STM.RollingQueue as RQ



data RollingQueue a Source

A RollingQueue is a bounded FIFO channel. When the size limit is exceeded, older entries are discarded to make way for newer entries.

Note: if the size limit is less than 1, write will have no effect, and read will always retry.

new :: Int -> STM (RollingQueue a)Source

Create a new, empty RollingQueue, with the given size limit.

To change the size limit later, use setLimit.

newIO :: Int -> IO (RollingQueue a)Source

IO variant of new. This is useful for creating top-level RollingQueues using unsafePerformIO, because performing atomically inside a pure computation is extremely dangerous (can lead to NestedAtomically errors and even segfaults, see GHC ticket #5866).


logQueue :: RollingQueue LogEntry
logQueue = unsafePerformIO (RQ.newIO 1000)
{-# NOINLINE logQueue #-}

write :: RollingQueue a -> a -> STM ()Source

Write an entry to the rolling queue. If the queue is full, discard the oldest entry.

There is no tryWrite, because write never retries.

read :: RollingQueue a -> STM (a, Int)Source

Read the next entry from the RollingQueue. retry if the queue is empty.

The Int is the number of entries discarded since the last read operation (usually 0).

tryRead :: RollingQueue a -> STM (Maybe (a, Int))Source

Like read, but do not retry. Instead, return Nothing if the queue is empty.

isEmpty :: RollingQueue a -> STM BoolSource

Test if the queue is empty.

length :: RollingQueue a -> STM IntSource

O(1) Get the number of items in the queue.

setLimit :: RollingQueue a -> Int -> STM ()Source

Adjust the size limit. Queue entries will be discarded if necessary to satisfy the new limit.

getLimit :: RollingQueue a -> STM IntSource

Get the current size limit. This will return 0 if a negative value was passed to new, newIO, or setLimit.


checkInvariants :: RollingQueue a -> STM ()Source

Verify internal structure. Throw a CheckException if the check fails, signifying a bug in the implementation.

dump :: Show a => RollingQueue a -> IO ()Source

Dump the RollingQueue (output and internal counters) to standard output. This calls checkInvariants first.