AdvSTM.hs

-----------------------------------------------------------------------------
-- |
-- Module      :  Control.Monad.AdvSTM
-- Copyright   :  (c) HaskellWiki 2006-2007, Peter Robinson 2008
-- License     :  BSD3
-- 
-- Maintainer  :  Peter Robinson <robinson@ecs.tuwien.ac.at>
-- Stability   :  experimental
-- Portability :  non-portable (requires STM)
--
-- Provides the type class MonadAdvSTM and the AdvSTM monad.
-- Parts of this implementation were taken from the HaskellWiki Page of
-- MonadAdvSTM (see package description).
-----------------------------------------------------------------------------
 

module Control.Monad.AdvSTM( MonadAdvSTM(..)
                           , AdvSTM
                           )
where
import Control.Monad.AdvSTM.Def
import Control.Monad.AdvSTM.Class

import Control.Exception(Exception)
import qualified Control.Concurrent.STM as S
import Control.Concurrent.STM.TVar(TVar) 
import Control.Concurrent.STM.TMVar(TMVar) 
import Control.Concurrent(MVar,ThreadId)
import Control.Monad(Monad,MonadPlus)
import Control.Monad.Reader(MonadReader,ReaderT)

{-
-- | A type class for extended-STM monads. See 'AdvSTM' for a concrete
-- instantiation
class Monad m => MonadAdvSTM m where
    -- | Takes an IO action that will be executed if the STM transaction commits. 
    -- /Beware:/ If the IO action throws an exception, the effects of the STM 
    -- action will still be visible.
    -- 
    -- /Atomicity and Race Conditions:/ 
    --
    -- * 'TVar', 'TChan', 'TArray' or 'TMVar': There is a race hole between the TM transaction 
    -- and the execution of the IO action, i.e., other
    -- transactions might commit before the IO action is run. 
    --
    -- * 'TTVar': When a 'TTVar' was modified in the TM action, it cannot be accessed by any 
    -- other thread before the onCommit IO action was run. Forking
    -- another thread inside of the onCommit IO action breaks this atomicity
    -- guarantee.
    onCommit  :: IO a -> m ()

    -- | Adds the IO action to the retry-queue. If the transaction retries,
    -- a new thread is forked that runs the retry actions. When this thread is
    -- done, the transaction retries.
    onRetry   :: IO a -> m ()

    -- | See 'S.orElse'
    orElse :: m a -> m a -> m a

    -- | See 'S.retry'
    retry  :: m a

    -- | Runs a transaction atomically in the 'IO' monad. 
    runAtomic :: m a -> IO a

    -- | See 'S.catchSTM'
    catchSTM  :: Exception e => m a -> (e -> m a) -> m a

    -- | Lifts STM actions to 'MonadAdvSTM'.
    liftAdv   :: S.STM a -> m a
-} 
--------------------------------------------------------------------------------
{-
-- | Drop-in replacement for the STM monad
newtype AdvSTM a = AdvSTM (ReaderT Env S.STM a)
                deriving ( Functor
                         , Monad
                         , MonadPlus
--                         , MonadReader Env
                         )

-}