stm-io-hooks-0.4.2: An STM monad with IO hooksSource codeContentsIndex
Control.Monad.AdvSTM
Portabilitynon-portable (requires STM)
Stabilityexperimental
MaintainerPeter Robinson <robinson@ecs.tuwien.ac.at>
Description
Provides the type class MonadAdvSTM and the AdvSTM monad. Parts of this implementation were taken from the HaskellWiki Page of MonadAdvSTM (see package description).
Synopsis
class Monad m => MonadAdvSTM m where
onCommit :: IO () -> m ()
onRetry :: IO () -> m ()
orElse :: m a -> m a -> m a
retry :: m a
check :: Bool -> m ()
alwaysSucceeds :: m a -> m ()
always :: m Bool -> m ()
catchSTM :: Exception e => m a -> (e -> m a) -> m a
liftAdv :: STM a -> m a
readTVar :: TVar a -> m a
writeTVar :: TVar a -> a -> m ()
newTVar :: a -> m (TVar a)
data AdvSTM a
Documentation
class Monad m => MonadAdvSTM m whereSource
A type class for extended-STM monads. For a concrete instantiation see AdvSTM
Methods
onCommit :: IO () -> m ()Source

Takes an IO action that will be executed iff the transaction commits.

  • When a TVar was modified in a transaction and this transaction commits, this update remains invisible to other threads until the corresponding onCommit action was run.
  • If the onCommit action throws an exception, the original value of the TVars will be restored.
  • Accessing a modified TVar within the onCommit action will cause a Deadlock exception to be thrown.

As a general rule, onCommit should only be used for "real" (i.e. without atomic blocks) IO actions and is certainly not the right place to fiddle with TVars. For example, if you wanted to write a TVar value to a file on commit, you could write:

 tvar <- newTVarIO "bla"
 atomically $ do 
    x <- readTVar tvar 
    onCommit (writeFile "myfile" x)
onRetrySource
:: IO ()IO action that will be run if the transaction is (explicitly) retried.
-> m ()

Adds an IO action to the retry job-queue. If the transaction retries, a new helper thread is forked that runs the retry actions, and, after the helper thread is done, the transaction retries.

Note: When the transaction is retried, unsafeIOToSTM is used to fork a helper thread that runs the retry actions (if any). It is your responsibility to ensure that your retry IO-actions are `safe'. Any exceptions occurring in the retry-thread will be thrown to the thread where the transaction is running and immediately cause the transaction to be aborted, since catchSTM does not catch asynchronous exceptions.

orElse :: m a -> m a -> m aSource
See orElse
retry :: m aSource
Runs any IO actions added by onRetry and then retries the transaction.
check :: Bool -> m ()Source
See check
alwaysSucceeds :: m a -> m ()Source
See alwaysSucceeds
always :: m Bool -> m ()Source
See always
catchSTM :: Exception e => m a -> (e -> m a) -> m aSource
See catchSTM
liftAdv :: STM a -> m aSource
Lifts STM actions to MonadAdvSTM.
readTVar :: TVar a -> m aSource
Reads a value from a TVar. Blocks until the IO onCommit action(s) of the corresponding transaction are complete. See onCommit for a more detailed description of this behaviour.
writeTVar :: TVar a -> a -> m ()Source
Writes a value to a TVar. Blocks until the onCommit IO-action(s) are complete. See onCommit for details.
newTVar :: a -> m (TVar a)Source
See newTVar
show/hide Instances
data AdvSTM a Source
Drop-in replacement for the STM monad
show/hide Instances
Produced by Haddock version 2.4.2