Haskus.Utils.STM

STM helpers

Documentation

data STM a :: * -> *

A monad supporting atomic memory transactions.

Instances

Monad STM

Since: 4.3.0.0

Methods

(>>=) :: STM a -> (a -> STM b) -> STM b

(>>) :: STM a -> STM b -> STM b

return :: a -> STM a

fail :: String -> STM a

Functor STM

Since: 4.3.0.0

Methods

fmap :: (a -> b) -> STM a -> STM b

(<$) :: a -> STM b -> STM a

Applicative STM

Since: 4.8.0.0

Methods

pure :: a -> STM a

(<*>) :: STM (a -> b) -> STM a -> STM b

liftA2 :: (a -> b -> c) -> STM a -> STM b -> STM c

(*>) :: STM a -> STM b -> STM b

(<*) :: STM a -> STM b -> STM a

Alternative STM

Since: 4.8.0.0

Methods

empty :: STM a

(<|>) :: STM a -> STM a -> STM a

some :: STM a -> STM [a]

many :: STM a -> STM [a]

MonadPlus STM

Since: 4.3.0.0

Methods

mzero :: STM a

mplus :: STM a -> STM a -> STM a

MonadBaseControl STM STM

Associated Types

type StM (STM :: * -> *) a :: *

Methods

liftBaseWith :: (RunInBase STM STM -> STM a) -> STM a

restoreM :: StM STM a -> STM a

type StM STM a

type StM STM a = a

retry :: STM a

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 udpated. (GHC only)

atomically :: MonadIO m => STM a -> m a

Execute an STM transaction atomically

TVar

data TVar a :: * -> *

Shared memory locations that support atomic memory transactions.

Instances

Eq (TVar a)

Since: 4.8.0.0

Methods

(==) :: TVar a -> TVar a -> Bool

(/=) :: TVar a -> TVar a -> Bool

Eq a => TEq (TVar a)

Methods

teq :: TVar a -> TVar a -> STM Bool

newTVarIO :: MonadIO m => a -> m (TVar a)

Create a TVar

readTVarIO :: MonadIO m => TVar a -> m a

Read a TVar in an IO monad

writeTVar :: TVar a -> a -> STM ()

Write the supplied value into a TVar

readTVar :: TVar a -> STM a

Return the current value stored in a TVar

newTVar :: a -> STM (TVar a)

Create a new TVar holding a value supplied

swapTVar :: TVar a -> a -> STM a

Swap the contents of a TVar for a new value.

modifyTVar :: TVar a -> (a -> a) -> STM ()

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

modifyTVar' :: TVar a -> (a -> a) -> STM ()

Strict version of modifyTVar.

TMVar

data TMVar a :: * -> *

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.

Instances

Eq (TMVar a)

Methods

(==) :: TMVar a -> TMVar a -> Bool

(/=) :: TMVar a -> TMVar a -> Bool

newTMVarIO :: MonadIO m => a -> m (TMVar a)

Create a TMVar

isEmptyTMVar :: TMVar a -> STM Bool

Check whether a given TMVar is empty.

newEmptyTMVar :: STM (TMVar a)

Create a TMVar which is initially empty.

newEmptyTMVarIO :: IO (TMVar a)

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

readTMVar :: TMVar a -> STM a

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

takeTMVar :: TMVar a -> STM a

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

putTMVar :: TMVar a -> a -> STM ()

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

swapTMVar :: TMVar a -> a -> STM a

Swap the contents of a TMVar for a new value.

tryReadTMVar :: TMVar a -> STM (Maybe a)

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

tryPutTMVar :: TMVar a -> a -> STM Bool

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.

tryTakeTMVar :: TMVar a -> STM (Maybe a)

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

data TChan a :: * -> *

TChan is an abstract type representing an unbounded FIFO channel.

Instances

Eq (TChan a)

Methods

(==) :: TChan a -> TChan a -> Bool

(/=) :: TChan a -> TChan a -> Bool

newBroadcastTChanIO :: MonadIO m => m (TChan a)

Create a broadcast channel

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

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

Write a value to a TChan.

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.

readTChan :: TChan a -> STM a

Read the next value from the TChan.