-- 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, also
-- available at
-- http://www.informatik.uni-kiel.de/prog/mitarbeiter/frank-kupke/.
--
-- Changes from last version:
--
--
-- - documentation available online
-- - fixed typos in Chat example
-- - set debug flags to no debug output
--
@package DSTM
@version 0.1.2
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