7b73edb43eb62c3669494996f256429c94a662cc
[acid-state-dist.git] / src / Data / Acid / Centered.hs
1 --------------------------------------------------------------------------------
2 {- |
3   Module      :  Data.Acid.Centered
4   Copyright   :  MIT
5
6   Maintainer  :  max.voit+hdv@with-eyes.net
7   Portability :  non-portable (uses GHC extensions)
8
9   A replication backend for acid-state that is centered around a Master node.
10   Slave nodes connect to the Master, are synchronized and get updated by the
11   Master continuously. This backend offers two flavors of operation:
12
13     [@Regular operation@]   No redundancy guarantees but fast.
14     [@Redundant operation@] Guarantees redundant replication on /n/ nodes but
15                             slower.
16
17   In both cases Slaves' Updates block (and eventually time out) if the Master is
18   unreachable.
19
20   Queries operate on the local state with the performance known from acid-state.
21   Note that state on all nodes is eventually consistent, i.e. it might differ
22   shortly (for Queries run concurrently to Updates being serialized).
23
24 -}
25
26 module Data.Acid.Centered
27     (
28 -- * Usage
29 -- |
30 -- Open your AcidState using one of the functions below. Afterwards the usual
31 -- interface of acid state is available.
32 --
33 -- Always make sure to have sensible exception management since naturally a lot
34 -- more error sources exist with this backend than do for a 'Data.Acid.Local'
35 -- AcidState.
36 -- Using 'Control.Exception.bracket' is recommended for achieving this
37 -- conveniently:
38 --
39 -- > main = bracket
40 -- >          (enslaveState ...)
41 -- >          closeAcidState
42 -- >          $ \acid -> do
43 -- >               ...
44 --
45 -- 'Data.Acid.createCheckpoint' issued on Master is a global operation,
46 -- while issued on a Slave it is not.
47 --
48 -- 'Data.Acid.createArchive' is an operation local to each node since usually
49 -- further action is required. For global Archives see 'createArchiveGlobally'.
50
51
52     -- * Regular operation
53     -- |
54     -- Running Updates on Master works as known from acid-state and with
55     -- negligible performance loss.
56     -- On Slaves Updates are delayed by approximately one round trip time (RTT).
57     -- When no Slaves are connected Updates are only serialized on the Master,
58     -- i.e. there is no redundancy.
59       openMasterState
60     , openMasterStateFrom
61     , enslaveState
62     , enslaveStateFrom
63     -- * Redundant operation
64     -- |
65     -- When Updates are scheduled they are sent out and written to disk on all
66     -- nodes. However, an Update is visible to Queries (and its result returned)
67     -- /only/ as soon as at least /n/ nodes are done replicating it. Thus each
68     -- Update is delayed for at least one RTT.
69     --
70     -- If less than /n-1/ Slave nodes are connected, all Updates are blocked
71     -- until enough nodes are available again. Queries are not affected and
72     -- operate on the last /n/-replicated state.
73     --
74     -- /Note:/ Shutting down and restarting the Master resumes the last state
75     -- including even Updates that were not /n/-replicated.
76     , openRedMasterState
77     , openRedMasterStateFrom
78     , enslaveRedState
79     , enslaveRedStateFrom
80     -- * Types
81     , PortNumber
82     ) where
83
84 import Data.Acid.Centered.Master
85 import Data.Acid.Centered.Slave
86 import Data.Acid.Centered.Common
87