1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Permanent Message Handling</title>
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Getting Started with Replicated Berkeley DB Applications" />
<link rel="up" href="repapp.html" title="Chapter 3. The DB Replication Manager" />
<link rel="prev" href="repmgr_init_example_c.html" title="Adding the Replication Manager to SimpleTxn" />
<link rel="next" href="electiontimes.html" title="Managing Election Times" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 11.2.5.3</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Permanent Message Handling</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a> </td>
<th width="60%" align="center">Chapter 3. The DB Replication Manager</th>
<td width="20%" align="right"> <a accesskey="n" href="electiontimes.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="fwrkpermmessage"></a>Permanent Message Handling</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="sect2">
<a href="fwrkpermmessage.html#fmwrkpermpolicy">Identifying Permanent Message Policies</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="fwrkpermmessage.html#fmwrkpermtimeout">Setting the Permanent Message Timeout</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="fwrkpermmessage.html#perm2fmwrkexample">Adding a Permanent Message Policy to
<span>RepQuoteExampleGSG</span>
</a>
</span>
</dt>
</dl>
</div>
<p>
As described in <a class="xref" href="permmessages.html" title="Permanent Message Handling">Permanent Message Handling</a>,
messages are marked permanent if they contain database
modifications that should be committed at the replica.
DB's replication code decides if it must flush its
transaction logs to disk depending on whether it receives
sufficient permanent message acknowledgments from the
participating replicas. More importantly, the thread
performing the transaction commit blocks
until it either receives enough acknowledgments, or the
acknowledgment timeout expires.
</p>
<p>
The Replication Manager is fully capable of managing permanent messages
for you if your application requires it (most do).
Almost all of the details of this are handled by the
Replication Manager for you. However, you do have to set some policies
that tell the Replication Manager how to handle permanent messages.
</p>
<p>
There are two things that you have to do:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
Determine how many acknowledgments
must be received by the master.
</p>
</li>
<li>
<p>
Identify the amount of time that
replicas have to send their
acknowledgments.
</p>
</li>
</ul>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="fmwrkpermpolicy"></a>Identifying Permanent Message Policies</h3>
</div>
</div>
</div>
<p>
You identify permanent message policies using the
<span>
<code class="classname">ReplicationManagerAckPolicy</code>
class which you pass to the environment
using the
<code class="methodname">EnvironmentConfig.setReplicationManagerAckPolicy</code>
method.
</span>
Note that you can set permanent message
policies at any time during the life of the
application.
</p>
<p>
The following permanent message policies are available when you use
the Replication Manager:
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
The following list mentions <span class="emphasis"><em>electable peer</em></span>
several times. This is simply another environment that can be
elected to be a master (that is, it has a priority greater than 0).
Do not confuse this with the concept of a peer as used for client
to client transfers. See <a class="xref" href="c2ctransfer.html" title="Client to Client Transfer">Client to Client Transfer</a> for more information on client
to client transfers.
</p>
</div>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<code class="literal">ReplicationManagerAckPolicy.NONE</code>
</p>
<p>
No permanent message acknowledgments are required. If
this policy is selected, permanent message handling is
essentially "turned off." That is, the master will
never wait for replica acknowledgments. In this case,
transaction log data is either flushed or not strictly
depending on the type of commit that is being performed
(synchronous or asynchronous).
</p>
</li>
<li>
<p>
<code class="literal">ReplicationManagerAckPolicy.ONE</code>
</p>
<p>
At least one replica must acknowledge the permanent
message within the timeout period.
</p>
</li>
<li>
<p>
<code class="literal">ReplicationManagerAckPolicy.ONE_PEER</code>
</p>
<p>
At least one electable peer must acknowledge the permanent
message within the timeout period.
</p>
</li>
<li>
<p>
<code class="literal">ReplicationManagerAckPolicy.ALL</code>
</p>
<p>
All replicas must acknowledge the message within
the timeout period. This
policy should be selected only if your replication
group has a small number of replicas, and those replicas
are on extremely reliable networks and servers.
</p>
</li>
<li>
<p>
<code class="literal">ReplicationManagerAckPolicy.ALL_AVAILABLE</code>
</p>
<p>
All currently connected replication clients must
acknowledge the message. This policy will invoke the
<code class="literal">DB_EVENT_REP_PERM_FAILED</code> event if
fewer than a quorum of clients acknowledged during that
time.
</p>
</li>
<li>
<p>
<code class="literal">ReplicationManagerAckPolicy.ALL_PEERS</code>
</p>
<p>
All electable peers must acknowledge the message within the
timeout period. This
policy should be selected only if your replication
group is small, and its various environments
are on extremely reliable networks and servers.
</p>
</li>
<li>
<p>
<code class="literal">ReplicationManagerAckPolicy.QUORUM</code>
</p>
<p>
A quorum of electable peers must acknowledge the message within the timeout period.
A quorum is reached when acknowledgments are received from the minimum number
of environments needed to ensure that the record remains durable
if an election is held. That is, the master wants to hear from enough
electable replicas that they have committed the record so that if an election
is held, the master knows the record will exist even if a new master is selected.
</p>
</li>
</ul>
</div>
<p>
By default, a quorum of electable peers must must acknowledge a permanent
message in order for it considered to have been successfully
transmitted.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="fmwrkpermtimeout"></a>Setting the Permanent Message Timeout</h3>
</div>
</div>
</div>
<p>
The permanent message timeout represents the
maximum amount of time the committing thread
will block waiting for message
acknowledgments. If sufficient
acknowledgments arrive before this timeout has
expired, the thread continues operations as
normal. However, if this timeout expires, the
committing thread flushes its transaction log
buffer before continuing with normal
operations.
</p>
<p>
You set the timeout value using
<code class="methodname">Environment.setReplicationTimeout()</code>.
You pass this method the
<code class="methodname">ReplicationTimeoutType.ACK_TIMEOUT</code>
constant and a timeout value in microseconds.
</p>
<p>
For example:
</p>
<pre class="programlisting"> dbenv.setReplicationTimeout(ReplicationTimeoutType.ACK_TIMEOUT, 100); </pre>
<p>
This timeout value can be set at anytime during the
life of the application.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="perm2fmwrkexample"></a>Adding a Permanent Message Policy to
<span>RepQuoteExampleGSG</span>
</h3>
</div>
</div>
</div>
<p>
For illustration purposes, we will now update
<code class="literal">RepQuoteExampleGSG</code>
such that it requires only one acknowledgment from
a replica on transactional commits. Also, we will give
this acknowledgment a 500 microsecond timeout
value. This means that our application's main
thread will block for up to 500 microseconds waiting
for an acknowledgment. If it does not receive at
least one acknowledgment in that amount of time,
DB will flush the transaction logs to disk
before continuing on.
</p>
<p>
This is a very simple update. We can perform the
entire thing in
<code class="methodname">RepQuoteExampleGSG.init()</code>
immediately after we set the application's priority
and before we open our environment handle.
</p>
<pre class="programlisting"> public int init(RepConfig config)
throws DatabaseException
{
int ret = 0;
repConfig = config;
EnvironmentConfig envConfig = new EnvironmentConfig();
envConfig.setErrorStream(System.err);
envConfig.setErrorPrefix(RepConfig.progname);
envConfig.addReplicationManagerSite(repConfig.getThisHost());
for (ReplicationHostAddress host =
repConfig.getFirstOtherHost();
host != null; host = repConfig.getNextOtherHost()){
ReplicationManagerSiteConfig repmgrRemoteSiteConfig =
new ReplicationManagerSiteConfig(host.host, host.port);
repmgrRemoteSiteConfig.setBootstrapHelper(true);
envConfig.addReplicationManagerSite(
repmgrRemoteSiteConfig);
}
envConfig.setReplicationPriority(appConfig.priority);
<strong class="userinput"><code>envConfig.setReplicationManagerAckPolicy(
ReplicationManagerAckPolicy.ALL);
envConfig.setReplicationTimeout(ReplicationTimeoutType.ACK_TIMEOUT,
500); </code></strong>
envConfig.setCacheSize(RepConfig.CACHESIZE);
envConfig.setTxnNoSync(true);
... </pre>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="repapp.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="electiontimes.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Adding the Replication Manager to
<span>SimpleTxn</span>
</td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Managing Election Times</td>
</tr>
</table>
</div>
</body>
</html>
|
