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

Contents

- The TMChan type
  - Creating TMChans
  - Reading from TMChans
  - Writing to TMChans
  - Closing TMChans
  - Predicates

Description

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

Synopsis

- data TMChan a
- newTMChan :: STM (TMChan a)
- newTMChanIO :: IO (TMChan a)
- dupTMChan :: TMChan a -> STM (TMChan a)
- newBroadcastTMChan :: STM (TMChan a)
- newBroadcastTMChanIO :: IO (TMChan a)
- readTMChan :: TMChan a -> STM (Maybe a)
- tryReadTMChan :: TMChan a -> STM (Maybe (Maybe a))
- peekTMChan :: TMChan a -> STM (Maybe a)
- tryPeekTMChan :: TMChan a -> STM (Maybe (Maybe a))
- writeTMChan :: TMChan a -> a -> STM ()
- unGetTMChan :: TMChan a -> a -> STM ()
- closeTMChan :: TMChan a -> STM ()
- isClosedTMChan :: TMChan a -> STM Bool
- isEmptyTMChan :: TMChan a -> STM Bool

# The TMChan type

data TMChan a

`TMChan` is an abstract type representing a closeable FIFO channel.

## Creating TMChans

newTMChan :: STM (TMChan a)

Build and returns a new instance of `TMChan`.

newTMChanIO :: IO (TMChan a)

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

dupTMChan :: TMChan a -> STM (TMChan a)

Duplicate a `TMChan`: the duplicate channel begins empty, but data written to either channel from then on will be available from both, and closing one copy will close them all. Hence this creates a kind of broadcast channel, where data written by anyone is seen by everyone else.

newBroadcastTMChan :: STM (TMChan a)

Like `newBroadcastTChan`.

Since: 2.1.0

newBroadcastTMChanIO :: IO (TMChan a)

`IO` version of `newBroadcastTMChan`.

Since: 2.1.0

## Reading from TMChans

readTMChan :: TMChan a -> STM (Maybe a)

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

tryReadTMChan :: TMChan a -> STM (Maybe (Maybe a))

A version of `readTMChan` which does not retry. Instead it returns `Just Nothing` if the channel is open but no value is available; it still returns `Nothing` if the channel is closed and empty.

peekTMChan :: TMChan a -> STM (Maybe a)

Get the next value from the `TMChan` without removing it, retrying if the channel is empty.

tryPeekTMChan :: TMChan a -> STM (Maybe (Maybe a))

A version of `peekTMChan` which does not retry. Instead it returns `Just Nothing` if the channel is open but no value is available; it still returns `Nothing` if the channel is closed and empty.

## Writing to TMChans

writeTMChan :: TMChan a -> a -> STM ()

Write a value to a `TMChan`. If the channel is closed then the value is silently discarded. Use `isClosedTMChan` to determine if the channel is closed before writing, as needed.

unGetTMChan :: TMChan a -> a -> STM ()

Put a data item back onto a channel, where it will be the next item read. If the channel is closed then the value is silently discarded; you can use `peekTMChan` to circumvent this in certain circumstances.

## Closing TMChans

closeTMChan :: TMChan a -> STM ()

Closes the `TMChan`, preventing any further writes.

## Predicates

isClosedTMChan :: TMChan a -> STM Bool

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

isEmptyTMChan :: TMChan a -> STM Bool

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