HORIZON HASKELLDocslts/ghc-10.0.x8c2f8e82026-10-19Search names, modules, packages, or :: a typeCtrl K

GHC 10.0.0.20260917 · lts/ghc-10.0.x · 8c2f8e8 · 2026-10-19

Moduleconcurrency-1.11.0.3Haskell2010

Control.Monad.STM.Class

This module provides an abstraction over STM, which can be used with MonadConc.

This module only defines the STM class; you probably want to import Control.Concurrent.Classy.STM (which exports Control.Monad.STM.Class).

Deriving instances: If you have a newtype wrapper around a type with an existing MonadSTM instance, you should be able to derive an instance for your type automatically, in simple cases.

For example:

{-# LANGUAGE GeneralizedNewtypeDeriving #-}
{-# LANGUAGE StandaloneDeriving #-}
{-# LANGUAGE UndecidableInstances #-}

data Env = Env

newtype MyMonad m a = MyMonad { runMyMonad :: ReaderT Env m a }
  deriving (Functor, Applicative, Monad, Alternative, MonadPlus)

deriving instance MonadThrow m => MonadThrow (MyMonad m)
deriving instance MonadCatch m => MonadCatch (MyMonad m)

deriving instance MonadSTM m => MonadSTM (MyMonad m)

Do not be put off by the use of UndecidableInstances, it is safe here.

Deviations: An instance of MonadSTM is not required to be a MonadFix, unlike STM.

  • 1 type
  • 1 class
  • 7 values
classclass (MonadCatch stm, MonadPlus stm) => MonadSTM (stm :: Type -> Type) where
#

MonadSTM is an abstraction over STM.

This class does not provide any way to run transactions, rather each MonadConc has an associated MonadSTM from which it can atomically run a transaction.

Associated types

  • type family TVar (stm :: Type -> Type) :: Type -> Type

    The mutable reference type. These behave like TVars, in that they always contain a value and updates are non-blocking and synchronised.

Methods

  • newTVar :: a -> stm (TVar stm a)

    Create a new TVar containing the given value.

    newTVar = newTVarN ""
  • newTVarN :: String -> a -> stm (TVar stm a)

    Create a new TVar containing the given value, but it is given a name which may be used to present more useful debugging information.

    If an empty name is given, a counter starting from 0 is used. If names conflict, successive TVars with the same name are given a numeric suffix, counting up from 1.

    newTVarN _ = newTVar
  • readTVar :: TVar stm a -> stm a

    Return the current value stored in a TVar.

  • writeTVar :: TVar stm a -> a -> stm ()

    Write the supplied value into the TVar.

Instances10MonadSTM, …
valueretry :: MonadSTM stm => stm a
#

Retry execution of this transaction because it has seen values in TVars that it shouldn't have. This will result in the thread running the transaction being blocked until any TVars referenced in it have been mutated.

This is just mzero.

valuecheck :: MonadSTM stm => Bool -> stm ()
#

Check whether a condition is true and, if not, call retry.

valueorElse :: MonadSTM stm => stm a -> stm a -> stm a
#

Run the first transaction and, if it retrys, run the second instead.

This is just mplus.

valuethrowSTM :: (MonadSTM stm, Exception e) => e -> stm a
#

Throw an exception. This aborts the transaction and propagates the exception.

Utilities for type shenanigans

3 declarations
newtypenewtype IsSTM (m :: Type -> Type) a
#

A value of type IsSTM m a can only be constructed if m has a MonadSTM instance.

Instances10Monad, Functor, MonadFail, Applicative, Alternative, MonadPlus, …
valuetoIsSTM :: MonadSTM m => m a -> IsSTM m a
#

Wrap an m a value inside an IsSTM if m has a MonadSTM instance.