Control.Concurrent.STM.Twilight
Contents
Description
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/
- data STM r p q a
- data Atomic
- data Twi
- data Safe
- gret :: Monadish m => a -> m p p a
- gbind :: Monadish m => m p q a -> (a -> m q r b) -> m p r b
- atomically :: (forall s. STM s p q a) -> IO a
- retry :: STM r p q a
- twilight :: STM r Atomic Twi Bool
- tryCommit :: STM r Twi Safe ()
- ignoreAllConflicts :: STM r a Safe ()
- reload :: STM r Twi Safe ()
- data TVar a
- newTVar :: a -> STM r p p (TVar a)
- newTVarIO :: a -> IO (TVar a)
- readTVar :: TVar a -> STM r Atomic Atomic a
- writeTVar :: TVar a -> a -> STM r Atomic Atomic ()
- data RTwiVar a
- data WTwiVar a
- readTVarR :: TVar a -> Tag r -> STM r Atomic Atomic (a, RTwiVar a)
- writeTVarR :: TVar a -> a -> STM r Atomic Atomic (WTwiVar a)
- rewriteTVar :: WTwiVar a -> a -> STM r p p ()
- rereadTVar :: RTwiVar a -> STM r p p a
- data Tag r
- newTag :: STM r Atomic Atomic (Tag r)
- markTVar :: TVar a -> Tag r -> STM r Atomic Atomic ()
- isInconsistent :: Tag r -> STM r p p Bool
- safeTwiIO :: IO a -> STM r Safe Safe a
- unsafeTwiIO :: IO a -> STM r p p a
Documentation
The STM monad, supporting atomic memory transactions. In Twilight, the STM monad parametrized by different transactional states.
Transactional workflow
atomically :: (forall s. STM s p q a) -> IO aSource
Perform a series of STM actions atomically.
twilight :: STM r Atomic Twi BoolSource
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 ()Source
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 ()Source
Ignore conflicting updates to any variables that the transaction has read.
reload :: STM r Twi Safe ()Source
Update all variables that the transaction has read with an atomic reload operation. This operation can only be done once.
Transactional variables
Transactional variable. It represents a shared memory locations that support atomic memory transactions.
newTVarIO :: a -> IO (TVar a)Source
Create a new TVar with the value supplied. This is useful for creating top-level TVars.
writeTVar :: TVar a -> a -> STM r Atomic Atomic ()Source
Modify a TVar by replacing its old value with the supplied one.
Read and write handles
Read handle associated to a TVar. It is only valid for the scope of one transaction.
Write handle associated to a TVar. It is only valid for the scope of one transaction.
readTVarR :: TVar a -> Tag r -> STM r Atomic Atomic (a, RTwiVar a)Source
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)Source
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 ()Source
Modify the TVar associated to the handle by replacing the value that is stored in it.
rereadTVar :: RTwiVar a -> STM r p p aSource
Obtain the value of the TVar as read before.
Grouping TVars with tags
Tag for grouping TVars. This allows simplified conflict checks for a group of TVars. They are only valid for the scope of one transaction.
isInconsistent :: Tag r -> STM r p p BoolSource
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 aSource
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 aSource
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.