stm-2.4.2: Software Transactional Memory

Portability | non-portable (requires STM)
Stability | experimental
Maintainer | libraries@haskell.org
Safe Haskell | Trustworthy

Control.Concurrent.STM.TChan

Contents

- TChans
  - Construction
  - Reading and writing

Description

TChan: Transactional channels (GHC only)

Synopsis

- data TChan a
- newTChan :: STM (TChan a)
- newTChanIO :: IO (TChan a)
- newBroadcastTChan :: STM (TChan a)
- newBroadcastTChanIO :: IO (TChan a)
- dupTChan :: TChan a -> STM (TChan a)
- readTChan :: TChan a -> STM a
- tryReadTChan :: TChan a -> STM (Maybe a)
- peekTChan :: TChan a -> STM a
- tryPeekTChan :: TChan a -> STM (Maybe a)
- writeTChan :: TChan a -> a -> STM ()
- unGetTChan :: TChan a -> a -> STM ()
- isEmptyTChan :: TChan a -> STM Bool
- cloneTChan :: TChan a -> STM (TChan a)

# TChans

data TChan a Source

`TChan` is an abstract type representing an unbounded FIFO channel.

Instances

Typeable1 TChan |
Eq (TChan a) |

## Construction

newTChan :: STM (TChan a)Source

Build and return a new instance of `TChan`

newTChanIO :: IO (TChan a)Source

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

newBroadcastTChan :: STM (TChan a)Source

Create a write-only `TChan`. More precisely, `readTChan` will `retry` even after items have been written to the channel. The only way to read a broadcast channel is to duplicate it with `dupTChan`.

Consider a server that broadcasts messages to clients:

    serve :: TChan Message -> Client -> IO loop
    serve broadcastChan client = do
        myChan <- dupTChan broadcastChan
        forever $ do
            message <- readTChan myChan
            send client message

The problem with using `newTChan` to create the broadcast channel is that if it is only written to and never read, items will pile up in memory. By using `newBroadcastTChan` to create the broadcast channel, items can be garbage collected after clients have seen them.

newBroadcastTChanIO :: IO (TChan a)Source

`IO` version of `newBroadcastTChan`.

dupTChan :: TChan a -> STM (TChan a)Source

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

## Reading and writing

readTChan :: TChan a -> STM aSource

Read the next value from the `TChan`.

tryReadTChan :: TChan a -> STM (Maybe a)Source

A version of `readTChan` which does not retry. Instead it returns `Nothing` if no value is available.

peekTChan :: TChan a -> STM aSource

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

tryPeekTChan :: TChan a -> STM (Maybe a)Source

A version of `peekTChan` which does not retry. Instead it returns `Nothing` if no value is available.

writeTChan :: TChan a -> a -> STM ()Source

Write a value to a `TChan`.

unGetTChan :: TChan a -> a -> STM ()Source

Put a data item back onto a channel, where it will be the next item read.

isEmptyTChan :: TChan a -> STM Bool Source

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

cloneTChan :: TChan a -> STM (TChan a)Source

Clone a `TChan`: similar to dupTChan, but the cloned channel starts with the same content available as the original channel.