Documentation

A monad supporting atomic memory transactions.

Retry execution of the current memory transaction because it has seen values in TVars which mean that it should not continue (e.g. the TVars represent a shared buffer that is now empty). The implementation may block the thread until one of the TVars that it has read from has been updated. (GHC only)

Execute an STM transaction atomically

Shared memory locations that support atomic memory transactions.

Create a TVar

Read a TVar in an IO monad

Write the supplied value into a TVar.

Write a TVar in an IO monad

Return the current value stored in a TVar.

Create a new TVar holding a value supplied

Swap the contents of a TVar for a new value.

Since: stm-2.3

Swap a TVar in an IO monad

Mutate the contents of a TVar. N.B., this version is non-strict.

Since: stm-2.3

Strict version of modifyTVar.

Since: stm-2.3

A TMVar is a synchronising variable, used for communication between concurrent threads. It can be thought of as a box, which may be empty or full.

Create a TMVar

Check whether a given TMVar is empty.

Create a TMVar which is initially empty.

IO version of newEmptyTMVar. This is useful for creating top-level TMVars using unsafePerformIO, because using atomically inside unsafePerformIO isn't possible.

This is a combination of takeTMVar and putTMVar; ie. it takes the value from the TMVar, puts it back, and also returns it.

Return the contents of the TMVar. If the TMVar is currently empty, the transaction will retry. After a takeTMVar, the TMVar is left empty.

Put a value into a TMVar. If the TMVar is currently full, putTMVar will retry.

Swap the contents of a TMVar for a new value.

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

Since: stm-2.3

A version of putTMVar that does not retry. The tryPutTMVar function attempts to put the value a into the TMVar, returning True if it was successful, or False otherwise.

A version of takeTMVar that does not retry. The tryTakeTMVar function returns Nothing if the TMVar was empty, or Just a if the TMVar was full with contents a. After tryTakeTMVar, the TMVar is left empty.

TChan is an abstract type representing an unbounded FIFO channel.

Create a broadcast channel

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

Write a value to a TChan.

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.

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

Since: stm-2.4

Read the next value from the TChan.