Control.Concurrent.STM.TChan

stm-2.4.4: Software Transactional Memory

Copyright | (c) The University of Glasgow 2004
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | experimental
Portability | non-portable (requires STM)
Safe Haskell | Trustworthy
Language | Haskell98

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

# TChans

data TChan a

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

Instances

Eq (TChan a) |

## Construction

newTChan :: STM (TChan a)

Build and return a new instance of `TChan`

newTChanIO :: IO (TChan a)

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

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.

Since: 2.4

newBroadcastTChanIO :: IO (TChan a)

`IO` version of `newBroadcastTChan`.

Since: 2.4

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

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.

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

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

Since: 2.4

## Reading and writing

readTChan :: TChan a -> STM a

Read the next value from the `TChan`.

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

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

peekTChan :: TChan a -> STM a

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

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

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

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

Write a value to a `TChan`.

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

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

isEmptyTChan :: TChan a -> STM Bool

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