-------------------------------------------------------------------------- {- | Module : Control.Concurrent.STM.MonadIO Copyright : (c) 2010 Galois, Inc. License : BSD-style (see the file libraries/base/LICENSE) Maintainer : John Launchbury, john@galois.com Stability : experimental Portability : concurrency, requires STM Overloads the standard operations on TVars, and TMVars as defined in Control.Concurrent.STM. TVars and MVars are often thought of as variables to be used in the STM monad. But in practice, they should be used just as frequently (if not more so) in any IO-like monad, with STM being used purely when a new atomic transaction is being defined. Thus we reverse the naming convention, and use the plain access names when in the IO-like monad, and use an explicit STM suffix when using the variables tentatively within the STM monad itself. TMVars are particularly valuable when used in an IO-like monad, because operations like readTMVar and modifyTMvar can guarantee the atomicity of the operation (unlike the corresponding operations over MVars). The standard operations on 'TVar' and 'TMVar' (such as 'writeTVar' or 'newEmptyTMVar') are overloaded over the 'MonadIO' class. A monad @m@ is declared an instance of 'MonadIO' by defining a function > liftIO :: IO a -> m a It also overloads the 'atomically' function, so that STM transactions can be defined from within any MonadIO monad. -} {-# OPTIONS_GHC -fno-warn-unused-do-bind #-} module Control.Concurrent.STM.MonadIO ( STM , atomically , always , alwaysSucceeds , retry , orElse , check , catchSTM , S.TVar , newTVar , readTVar , writeTVar , registerDelay , modifyTVar , modifyTVar_ , newTVarSTM , readTVarSTM , writeTVarSTM , S.TMVar , newTMVar , newEmptyTMVar , takeTMVar , putTMVar , readTMVar , swapTMVar , tryTakeTMVar , tryPutTMVar , isEmptyTMVar , modifyTMVar , modifyTMVar_ , newTMVarSTM , newEmptyTMVarSTM , takeTMVarSTM , putTMVarSTM , readTMVarSTM , swapTMVarSTM , tryTakeTMVarSTM , tryPutTMVarSTM , isEmptyTMVarSTM ) where import Control.Monad.STM hiding (atomically) import qualified Control.Concurrent.STM as S import Control.Concurrent.MonadIO import GHC.Conc (readTVarIO) ------------------------------------------------------------------------- -- | The atomically function allows STM to be called directly from any -- monad which contains IO, i.e. is a member of MonadIO. atomically :: MonadIO io => STM a -> io a atomically m = liftIO $ S.atomically m ------------------------------------------------------------------------- type TVar = S.TVar newTVar :: MonadIO io => a -> io (TVar a) newTVar x = liftIO $ S.newTVarIO x readTVar :: MonadIO io => TVar a -> io a readTVar t = liftIO $ readTVarIO t writeTVar :: MonadIO io => TVar a -> a -> io () writeTVar t x = atomically $ writeTVarSTM t x registerDelay :: MonadIO io => Int -> io (TVar Bool) registerDelay n = liftIO $ S.registerDelay n -- | 'modifyTVar' is an atomic update operation which provides both -- the former value and the newly computed value as a result. modifyTVar :: MonadIO io => TVar a -> (a -> a) -> io (a,a) modifyTVar t f = atomically $ do x <- readTVarSTM t let y = f x seq y $ writeTVarSTM t y return (x,y) modifyTVar_ :: MonadIO io => TVar a -> (a -> a) -> io () modifyTVar_ t f = atomically $ do x <- readTVarSTM t let y = f x seq y $ writeTVarSTM t y ---------------------- newTVarSTM :: a -> STM (TVar a) newTVarSTM x = S.newTVar x readTVarSTM :: TVar a -> STM a readTVarSTM t = S.readTVar t writeTVarSTM :: TVar a -> a -> STM () writeTVarSTM t x = S.writeTVar t x ------------------------------------------------------------------------- type TMVar a = S.TMVar a newTMVar :: MonadIO io => a -> io (TMVar a) newTMVar x = liftIO $ S.newTMVarIO x newEmptyTMVar :: MonadIO io => io (TMVar a) newEmptyTMVar = liftIO $ S.newEmptyTMVarIO takeTMVar :: MonadIO io => TMVar a -> io a takeTMVar t = atomically $ takeTMVarSTM t putTMVar :: MonadIO io => TMVar a -> a -> io () putTMVar t x = atomically $ putTMVarSTM t x readTMVar :: MonadIO io => TMVar a -> io a readTMVar t = atomically $ readTMVarSTM t swapTMVar :: MonadIO io => TMVar a -> a -> io a swapTMVar t x = atomically $ swapTMVarSTM t x tryTakeTMVar :: MonadIO io => TMVar a -> io (Maybe a) tryTakeTMVar t = atomically $ tryTakeTMVarSTM t tryPutTMVar :: MonadIO io => TMVar a -> a -> io Bool tryPutTMVar t x = atomically $ tryPutTMVarSTM t x isEmptyTMVar :: MonadIO io => TMVar a -> io Bool isEmptyTMVar t = atomically $ isEmptyTMVarSTM t -- modifyTMVar is an atomic update operation which provides both -- the former value and the newly computed value as a result. modifyTMVar :: MonadIO io => TMVar a -> (a -> a) -> io (a,a) modifyTMVar t f = atomically $ do x <- takeTMVarSTM t let y = f x seq y $ putTMVarSTM t y return (x,y) modifyTMVar_ :: MonadIO io => TMVar a -> (a -> a) -> io () modifyTMVar_ t f = atomically $ do x <- takeTMVarSTM t let y = f x seq y $ putTMVarSTM t y ---------------------- newTMVarSTM :: a -> STM (TMVar a) newTMVarSTM = S.newTMVar newEmptyTMVarSTM :: STM (TMVar a) newEmptyTMVarSTM = S.newEmptyTMVar takeTMVarSTM :: TMVar a -> STM a takeTMVarSTM = S.takeTMVar putTMVarSTM :: TMVar a -> a -> STM () putTMVarSTM = S.putTMVar readTMVarSTM :: TMVar a -> STM a readTMVarSTM = S.readTMVar swapTMVarSTM :: TMVar a -> a -> STM a swapTMVarSTM = S.swapTMVar tryTakeTMVarSTM :: TMVar a -> STM (Maybe a) tryTakeTMVarSTM = S.tryTakeTMVar tryPutTMVarSTM :: TMVar a -> a -> STM Bool tryPutTMVarSTM = S.tryPutTMVar isEmptyTMVarSTM :: TMVar a -> STM Bool isEmptyTMVarSTM = S.isEmptyTMVar