fwrkpermmessage.html [plain text]
<?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.62.4" />
<link rel="home" href="index.html" title="Getting Started with Replicated Berkeley DB Applications" />
<link rel="up" href="repapp.html" title="Chapter 3. The DB Replication Framework" />
<link rel="previous" href="repmgr_init_example_c.html" title="Adding the Replication Framework to SimpleTxn " />
<link rel="next" href="electiontimes.html" title="Managing Election Times" />
</head>
<body>
<div class="navheader">
<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 Framework</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>
</div>
<p>
As described in <a href="permmessages.html">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 replica. More importantly, the thread
performing the transaction commit blocks
until it either receives enough acknowledgments, or the
acknowledgment timeout expires.
</p>
<p>
The replication framework 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 framework for you. However, you do have to set some policies
that tell the replication framework 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></div>
</div>
<p>
You identify permanent message policies using the
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 framework:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<tt class="literal">DB_REPMGR_ACKS_NONE</tt>
</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>
<tt class="literal">DB_REPMGR_ACKS_ONE</tt>
</p>
<p>
At least one replica must acknowledge the permanent
message within the timeout period.
</p>
</li>
<li>
<p>
<tt class="literal">DB_REPMGR_ACKS_ONE_PEER</tt>
</p>
<p>
At least one electable peer must acknowledge the permanent
message within the timeout period.
Note that an
<span class="emphasis"><em>electable peer</em></span> 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 href="c2ctransfer.html">Client to Client Transfer</a>
for more information on client to client transfers.
</p>
</li>
<li>
<p>
<tt class="literal">DB_REPMGR_ACKS_ALL</tt>
</p>
<p>
All environments 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>
<p>
When this flag is used, the actual number of
environments that must respond is
determined by the value set for
<span><tt class="methodname">DbEnv::rep_set_nsites()</tt>.</span>
</p>
</li>
<li>
<p>
<tt class="literal">DB_REPMGR_ACKS_ALL_PEERS</tt>
</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>
<p>
Note that an
<span class="emphasis"><em>electable peer</em></span> 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 href="c2ctransfer.html">Client to Client Transfer</a>
for more information on client to client transfers.
</p>
</li>
<li>
<p>
<tt class="literal">DB_REPMGR_ACKS_QUORUM</tt>
</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>
<p>
Note that an
<span class="emphasis"><em>electable peer</em></span> 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 href="c2ctransfer.html">Client to Client Transfer</a>
for more information on client to client transfers.
</p>
</li>
</ul>
</div>
<p>
By default, a quorum of sites must must acknowledge a permanent
message in order for it considered to have been successfully
transmitted. The actual number of environments that must respond is
calculated using the value set with
<span><tt class="methodname">DbEnv::rep_set_nsites()</tt>.</span>
</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></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 the
<tt class="methodname">DbEnv::rep_set_timeout()</tt>
method. When you do this, you provide the
<tt class="literal">DB_REP_ACK_TIMEOUT</tt> flag to
the <tt class="literal">which</tt> parameter, and the
timeout value in microseconds to the
<tt class="literal">timeout</tt> parameter.
</p>
<p>
For example:
</p>
<pre class="programlisting"> dbenv->rep_set_timeout(DB_REP_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>RepMgr</span>
</h3>
</div>
</div>
<div></div>
</div>
<p>
For illustration purposes, we will now update
<tt class="literal">RepMgr</tt>
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
<tt class="methodname">RepMgr::init()</tt>
immediately after we set the application's priority
and before we open our environment handle.
</p>
<pre class="programlisting">int RepMgr::init(RepConfigInfo *config)
{
int ret = 0;
app_config = config;
dbenv.set_errfile(stderr);
dbenv.set_errpfx(progname);
if ((ret = dbenv.repmgr_set_local_site(app_config->this_host.host,
app_config->this_host.port, 0)) != 0) {
cerr << "Could not set listen address to host:port "
<< app_config->this_host.host << ":"
<< app_config->this_host.port
<< "error: " << ret << endl;
}
for ( REP_HOST_INFO *cur = app_config->other_hosts; cur != NULL;
cur = cur->next) {
if ((ret = dbenv.repmgr_add_remote_site(cur->host, cur->port,
NULL, 0)) != 0) {
cerr << "could not add site." << endl
}
}
if (app_config->totalsites > 0) {
try {
if ((ret = dbenv.rep_set_nsites(app_config->totalsites)) != 0)
dbenv.err(ret, "set_nsites");
} catch (DbException dbe) {
cerr << "rep_set_nsites call failed. Continuing." << endl;
}
}
dbenv.rep_set_priority(app_config->priority);
<b class="userinput"><tt>/* Permanent messages require at least one ack */
dbenv.repmgr_set_ack_policy(DB_REPMGR_ACKS_ONE);
/* Give 500 microseconds to receive the ack */
dbenv.rep_set_timeout(DB_REP_ACK_TIMEOUT, 500);</tt></b>
dbenv.set_cachesize(0, CACHESIZE, 0);
dbenv.set_flags(DB_TXN_NOSYNC, 1);
... </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 Framework to
SimpleTxn
</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>