Data.STM.RollingQueue

This module is usually imported qualified:

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

Documentation

data RollingQueue a

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.

Instances

Typeable1 RollingQueue

Eq (RollingQueue a)

new :: Int -> STM (RollingQueue a)

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

To change the size limit later, use setLimit.

newIO :: Int -> IO (RollingQueue a)

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

Example:

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

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

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)

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

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

isEmpty :: RollingQueue a -> STM Bool

Test if the queue is empty.

length :: RollingQueue a -> STM Int

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

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

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

getLimit :: RollingQueue a -> STM Int

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

Debugging

checkInvariants :: RollingQueue a -> STM ()

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

data CheckException

Constructors

CheckException String

Instances

Show CheckException

Typeable CheckException

Exception CheckException

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

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