Control.Concurrent.STM.Twilight

The Twilight STM enhances a transaction with twilight code that executes between the preparation to commit the transaction and its actual commit or abort. Twilight code runs irrevocably and concurrently with the rest of the program. It can detect and repair potential read inconsistencies in the state of its transaction and may thus turn a failing transaction into a successful one. Moreover, twilight code can safely use I/O operations while modifying the transactionally managed memory.

More information and publications can be found at http://proglang.informatik.uni-freiburg.de/projects/twilight/

Documentation

data STM r p q a

The STM monad, supporting atomic memory transactions. In Twilight, the STM monad parametrized by different transactional states.

Instances

Monadish (STM r)

Monad (STM r p q)

data Atomic

Type of the atomic phase.

data Twi

Type of the twilight phase.

data Safe

Type of the safe phase.

gret :: Monadish m => a -> m p p a

gbind :: Monadish m => m p q a -> (a -> m q r b) -> m p r b

Transactional workflow

atomically :: (forall s. STM s p q a) -> IO a

Perform a series of STM actions atomically.

retry :: STM r p q a

Abort and restart the transaction.

twilight :: STM r Atomic Twi Bool

Going from the Atomic phase and the Twi phase. The return value indicates if there were intermediate updates to the variables that have been read.

tryCommit :: STM r Twi Safe ()

Phase transition from Twi phase to Safe phase. It will fail if there are inconsistencies in form of intermediate updates to the variables that the transaction has read.

ignoreAllConflicts :: STM r a Safe ()

Ignore conflicting updates to any variables that the transaction has read.

reload :: STM r Twi Safe ()

Update all variables that the transaction has read with an atomic reload operation. This operation can only be done once.

Transactional variables

data TVar a

Transactional variable. It represents a shared memory locations that support atomic memory transactions.

Instances

Eq (TVar a)

Show (TVar a)

newTVar :: a -> STM r p p (TVar a)

Create a new TVar containing the value that is supplied.

newTVarIO :: a -> IO (TVar a)

Create a new TVar with the value supplied. This is useful for creating top-level TVars.

readTVar :: TVar a -> STM r Atomic Atomic a

Return the current value stored in a TVar.

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

Modify a TVar by replacing its old value with the supplied one.

Read and write handles

data RTwiVar a

Read handle associated to a TVar. It is only valid for the scope of one transaction.

Instances

Eq (RTwiVar a)

Show (RTwiVar a)

data WTwiVar a

Write handle associated to a TVar. It is only valid for the scope of one transaction.

Instances

Eq (WTwiVar a)

Show (WTwiVar a)

readTVarR :: TVar a -> Tag r -> STM r Atomic Atomic (a, RTwiVar a)

Return the current value stored in a TVar, together with a read handle to the TVar which can be used for further read access to the TVar.

writeTVarR :: TVar a -> a -> STM r Atomic Atomic (WTwiVar a)

Modify a TVar by replacing its old value with the supplied one. The function returns a write handle to the TVar which can be used for latter modifications of this TVar.

rewriteTVar :: WTwiVar a -> a -> STM r p p ()

Modify the TVar associated to the handle by replacing the value that is stored in it.

rereadTVar :: RTwiVar a -> STM r p p a

Obtain the value of the TVar as read before.

Grouping TVars with tags

data Tag r

Tag for grouping TVars. This allows simplified conflict checks for a group of TVars. They are only valid for the scope of one transaction.

newTag :: STM r Atomic Atomic (Tag r)

Create a new tag.

markTVar :: TVar a -> Tag r -> STM r Atomic Atomic ()

Mark a variable with a tag.

isInconsistent :: Tag r -> STM r p p Bool

Checks if any of the variables that are marked with the tag are inconsistent because of intermediate updates by other transaction.

Embedding I/O

safeTwiIO :: IO a -> STM r Safe Safe a

Embed an IO action into the safe phase of the transaction. The transaction does not restart and re-execute this action unless specified by the programmer.

unsafeTwiIO :: IO a -> STM r p p a

Embed an IO action into any phase of the transaction. Due to conflicts with other transactions, this action will be re-executed if the transaction aborts and restarts.