Skip to content
Newer
Older
100644 124 lines (57 sloc) 3.39 KB
c1da173 Added some documentation + customizable fetch strategy
Ulf Wiger authored Mar 23, 2011
1
2
7b82193 @uwiger use plain rebar ct to run CT suite
authored Jan 22, 2012
3 #unsplit - A framework for resolving Mnesia netsplits#
c1da173 Added some documentation + customizable fetch strategy
Ulf Wiger authored Mar 23, 2011
4
5
7b82193 @uwiger use plain rebar ct to run CT suite
authored Jan 22, 2012
6 Copyright (c) 2010 Erlang Solutions Ltd.
c1da173 Added some documentation + customizable fetch strategy
Ulf Wiger authored Mar 23, 2011
7
8 __Version:__ 0.5
9
10
11
12 Unsplit is a framework for registering merge functions that will be
13 called any time mnesia tries to heal from netsplits.
14
15
16
17 The default behaviour of mnesia is not to attempt automatic merge after
18 a 'partitioned network' event. It detects and reports the condition, but
19 leaves it up to the user to resolve the problem.
20
21
22
23 Mnesia itself offers a few remedies: restart from backup, or elect to
24 unconditionally reload tables from one or more nodes - in both cases
25 data loss is very likely.
26
27
28
29 Unsplit starts a subscription on the 'partitioned network' event, and
30 forces Mnesia to merge the "islands" that have been separated. It inserts
31 itself into the schema merge transaction, claiming table locks on all
32 affected tables. It then runs user-provided merge callbacks for each
33 table, fetching data from one side, comparing the objects, and writing
34 back the data that should be kept.
35
36
37
38 Writing an Unsplit method
39 =========================
40
41
42
43 Unsplit methods are table-specific, although a default method can be set
44 using the `unsplit` application environment variable
45
46
47
48 `{default_method, {Module, Function, ExtraArgs}}`
49
50
51
52 The given method is called with the following arguments:
53
54
55
56 `apply(Module, Function, [init, Table, Attributes | ExtraArgs]) -> ret()`
57
58
59
60 to set up the merge. Then, data will be fetched using a given fetch strategy,
61 and the fetched data will be handed to the merge function as:
62
63
64
65 `apply(Module, Function, [data(), state()]) -> ret()`
66
67
68
69 The return value, `ret()` is defined as:
70
71 <pre>
72 ret() :: stop
7b82193 @uwiger use plain rebar ct to run CT suite
authored Jan 22, 2012
73 | {ok, state()}
74 | {ok, actions(), state()}
75 | {ok, actions(), strategy(), state()}
c1da173 Added some documentation + customizable fetch strategy
Ulf Wiger authored Mar 23, 2011
76
77 actions() :: [action()]
78
79 action() :: {write, Objects} | {delete, Objects}
80
81 strategy() :: all_keys | {ModS, FunS}
82 </pre>
83
84
85
86 If a custom fetch strategy function is given, it will be called as
87
88
89
90 `apply(ModS, FunS, [Table, RemoteNode, state()]) -> {ok, data(), state()}`
91
92
93
94 Note that `state()` is whatever the merge function creates. The unsplit
95 framework treats it as an opaque object, but the fetch function needs to
96 do the same, or be aware of its definition.
97
98
99
100 The format of `data()` can be anything that the merge function accepts,
101 but if the built-in strategy `all_keys` is used, it will have the format:
102
103
104
105 `data() :: [{[object()], [object()]}]`
106
107 where each 2-tuple represents the data matching a given key on each
108 side of the split. Thus, `[{[{mytab, 1, a}], []}]` would mean that the
109 object `{mytab, 1, a}` only exists on the side where the merge process is
110 running, but is not found on the other side. `[{[{mytab,2,a}], [{mytab,2,b}]}]`
111 would mean that conflicting versions of the object `{mytab,2}` were found.
112
113
7b82193 @uwiger use plain rebar ct to run CT suite
authored Jan 22, 2012
114 ##Modules##
c1da173 Added some documentation + customizable fetch strategy
Ulf Wiger authored Mar 23, 2011
115
116
117 <table width="100%" border="0" summary="list of modules">
7b82193 @uwiger use plain rebar ct to run CT suite
authored Jan 22, 2012
118 <tr><td><a href="http://github.com/esl/unsplit/blob/master/doc/unsplit.md" class="module">unsplit</a></td></tr>
119 <tr><td><a href="http://github.com/esl/unsplit/blob/master/doc/unsplit_lib.md" class="module">unsplit_lib</a></td></tr>
120 <tr><td><a href="http://github.com/esl/unsplit/blob/master/doc/unsplit_reporter.md" class="module">unsplit_reporter</a></td></tr>
121 <tr><td><a href="http://github.com/esl/unsplit/blob/master/doc/unsplit_server.md" class="module">unsplit_server</a></td></tr>
122 <tr><td><a href="http://github.com/esl/unsplit/blob/master/doc/unsplit_vclock.md" class="module">unsplit_vclock</a></td></tr></table>
c1da173 Added some documentation + customizable fetch strategy
Ulf Wiger authored Mar 23, 2011
123
Something went wrong with that request. Please try again.