Control.Concurrent.STM.TMQueue

stm-chans-3.0.0.4: Additional types of channels for STM.

Copyright | Copyright (c) 2011--2015 wren gayle romano
License | BSD
Maintainer | wren@community.haskell.org
Stability | provisional
Portability | non-portable (GHC STM, DeriveDataTypeable)
Safe Haskell | Trustworthy
Language | Haskell98

Control.Concurrent.STM.TMQueue

Contents

- The TMQueue type
  - Creating TMQueues
  - Reading from TMQueues
  - Writing to TMQueues
  - Closing TMQueues
  - Predicates

Description

A version of Control.Concurrent.STM.TQueue where the queue is closeable. This is similar to a `TQueue (Maybe a)` with a monotonicity guarantee that once there's a `Nothing` there will always be `Nothing`.

Since: 2.0.0

Synopsis

- data TMQueue a
- newTMQueue :: STM (TMQueue a)
- newTMQueueIO :: IO (TMQueue a)
- readTMQueue :: TMQueue a -> STM (Maybe a)
- tryReadTMQueue :: TMQueue a -> STM (Maybe (Maybe a))
- peekTMQueue :: TMQueue a -> STM (Maybe a)
- tryPeekTMQueue :: TMQueue a -> STM (Maybe (Maybe a))
- writeTMQueue :: TMQueue a -> a -> STM ()
- unGetTMQueue :: TMQueue a -> a -> STM ()
- closeTMQueue :: TMQueue a -> STM ()
- isClosedTMQueue :: TMQueue a -> STM Bool
- isEmptyTMQueue :: TMQueue a -> STM Bool

# The TMQueue type

data TMQueue a

`TMQueue` is an abstract type representing a closeable FIFO queue.

## Creating TMQueues

newTMQueue :: STM (TMQueue a)

Build and returns a new instance of `TMQueue`.

newTMQueueIO :: IO (TMQueue a)

`IO` version of `newTMQueue`. This is useful for creating top-level `TMQueue`s using `unsafePerformIO`, because using `atomically` inside `unsafePerformIO` isn't possible.

## Reading from TMQueues

readTMQueue :: TMQueue a -> STM (Maybe a)

Read the next value from the `TMQueue`, retrying if the queue is empty (and not closed). We return `Nothing` immediately if the queue is closed and empty.

tryReadTMQueue :: TMQueue a -> STM (Maybe (Maybe a))

A version of `readTMQueue` 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.

peekTMQueue :: TMQueue a -> STM (Maybe a)

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

tryPeekTMQueue :: TMQueue a -> STM (Maybe (Maybe a))

A version of `peekTMQueue` 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 TMQueues

writeTMQueue :: TMQueue a -> a -> STM ()

Write a value to a `TMQueue`. If the queue is closed then the value is silently discarded. Use `isClosedTMQueue` to determine if the queue is closed before writing, as needed.

unGetTMQueue :: TMQueue 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 `peekTMQueue` to circumvent this in certain circumstances.

## Closing TMQueues

closeTMQueue :: TMQueue a -> STM ()

Closes the `TMQueue`, preventing any further writes.

## Predicates

isClosedTMQueue :: TMQueue a -> STM Bool

Returns `True` if the supplied `TMQueue` has been closed.

isEmptyTMQueue :: TMQueue a -> STM Bool

Returns `True` if the supplied `TMQueue` is empty.