-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A framework for using STM within distributed systems
--
--
-- - The DSTM package consists of the DSTM library, a name server
-- application, and three sample distributed programs using the library.
-- DSTM is a framework enabling the use of the STM interface, known from
-- concurrent programming, to be used for distributed Haskell
-- applications as well. Provided are a simple Dining Philosophers, a
-- Chat, and a soft real-time Bomberman game application. Distributed
-- communication is transparent to the application programmer. The
-- application designer uses a very simple nameserver mechanism to set up
-- the system. The DSTM library includes the management of unavailable
-- process nodes and provides the application with abstract error
-- information thus facilitating the implementation of robust distributed
-- application programs. For usage please look into the included file:
-- DSTMManual.pdf. -
--
@package DSTM
@version 0.1.1
module Control.Distributed.STM.DSTM
-- | Shared memory locations that support atomic memory transactions.
-- Between different nodes memory is shared using transparent process
-- communication. (TVars are called host TVars when they reside
-- on the process where they have been created by calling
-- newTVar. They are called link TVars on other
-- processes)
data TVar a
-- | A monad supporting atomic memory transactions
data STM a
-- | Create a new TVar holding a value supplied
newTVar :: (Dist a) => a -> STM (TVar a)
-- | Return the current value stored in a TVar
readTVar :: (Dist a) => TVar a -> STM a
-- | Write the supplied value into a TVar
writeTVar :: (Dist a) => TVar a -> a -> STM ()
-- | Perform a series of STM actions atomically
atomic :: (Show a) => STM a -> IO a
-- | Retry execution of the current memory transaction because it has seen
-- values in TVars which mean that it should not continue (e.g. the TVars
-- represent a shared buffer that is now empty). The implementation may
-- block the thread until one of the TVars that it has read from has been
-- udpated.
retry :: STM a
-- | Compose two alternative STM actions. If the first action completes
-- without retrying then it forms the result of the orElse. Otherwise, if
-- the first action retries, then the second action is tried in its
-- place. If both actions retry then the orElse as a whole retries
orElse :: STM a -> STM a -> STM a
-- | Throw an exception within an STM action
throw :: SomeException -> STM a
-- | Exception handling within STM actions
catch :: STM a -> (SomeException -> STM a) -> STM a
-- | The class Dist defines the distribution property of
-- TVar values. Any TVar value must implement class Dist.
-- All basic data types exported by the Prelude are instances of
-- Dist, and Dist may be derived for any data type whose
-- constituents are also instances of Dist. Any custom-typed TVar
-- value type should implement finTVars and regTVars to do
-- nothing and return '()'.
--
-- Note that finTVars and regTVars should never be called
-- by the application itself!
class (Show a, Read a) => Dist a
regTVars :: (Dist a) => EnvAddr -> a -> IO ()
finTVars :: (Dist a) => a -> IO ()
nameService :: String -> IO ()
-- | The default name server for the process running the main function.
-- Usually it is localhost.
gDefaultNameServer :: String
-- | registerTVar server tVar name registers tVar
-- with name onto server
registerTVar :: (Dist a) => String -> TVar a -> String -> IO ()
-- | deregisterTVar server name removes name from
-- server
deregisterTVar :: String -> String -> IO ()
-- | lookupTVar server name returns (Just
-- tVar) if a tVar registration of name exists
-- on server, Nothing otherwise.
lookupTVar :: (Dist a) => String -> String -> IO (Maybe (TVar a))
-- | startDist enables inter process communication and exception
-- handling and then executes the given main function
startDist :: IO () -> IO ()
-- | SomeDistTVarException is the abstract exception type which is
-- thrown by the DSTM library when either readTVar or
-- writeTVar is called on an unreachable TVar. A TVar becomes
-- unreachable when the process hosting the TVar becomes unreachable. An
-- atomic transaction using a TVar which becomes unreachable during the
-- execution of atomic may either execute completely (without
-- the unreachable TVar(s)) or execute not at all depending on
-- transaction states. In either case an exception of type
-- SomeDistTVarException is raised.
data SomeDistTVarException
-- | isDistErrTVar e tVar checks whether
-- tVar is unreachable when exception e had been
-- raised. It returns True if the exception raised denotes
-- tVar as unreachable, False otherwise. A TVar returning
-- True once will never return a False check result.
isDistErrTVar :: SomeDistTVarException -> TVar a -> Bool
instance Show AutoLink