Control.Concurrent.STM.TChan

Copyright	(c) The University of Glasgow 2004
License	BSD-style (see the file libraries/base/LICENSE)
Maintainer	[email protected]
Stability	experimental
Portability	non-portable (requires STM)
Safe Haskell	Trustworthy
Language	Haskell2010

TChans

data TChan a Source

TChan is an abstract type representing an unbounded FIFO channel.

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

Since: stm-2.4

newBroadcastTChanIO :: IO (TChan a) Source

IO version of newBroadcastTChan.

Since: stm-2.4

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.

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.

Since: stm-2.4

Reading and writing

readTChan :: TChan a -> STM a Source

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.

Since: stm-2.3

peekTChan :: TChan a -> STM a Source

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

Since: stm-2.3

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

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

Since: stm-2.3

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.