mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 09:06:25 +00:00
210 lines
11 KiB
HTML
210 lines
11 KiB
HTML
<?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>Synchronizing with a master</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="Berkeley DB Programmer's Reference Guide" />
|
||
<link rel="up" href="rep.html" title="Chapter 12. Berkeley DB Replication" />
|
||
<link rel="prev" href="rep_elect.html" title="Elections" />
|
||
<link rel="next" href="rep_init.html" title="Initializing a new site" />
|
||
</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">Synchronizing with a master</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="rep_elect.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 12.
|
||
Berkeley DB Replication
|
||
</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="rep_init.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="rep_mastersync"></a>Synchronizing with a master</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="toc">
|
||
<dl>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="rep_mastersync.html#rep_delay_sync">Delaying client synchronization</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="rep_mastersync.html#rep_c2c_sync">Client-to-client synchronization</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="rep_mastersync.html#idp2309616">Blocked client operations</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="rep_mastersync.html#idp2331664">Clients too far out-of-date to synchronize</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<p>When a client detects a new replication group master, the client must
|
||
synchronize with the new master before the client can process new
|
||
database changes. Synchronizing is a heavyweight operation which can
|
||
place a burden on both the client and the master. There are several
|
||
controls an application can use to reduce the synchronization burden.</p>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="rep_delay_sync"></a>Delaying client synchronization</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>When a replication group has a new master, either as specified by the
|
||
application or as a result of winning an election, all clients in the
|
||
replication group must synchronize with the new master. This can
|
||
strain the resources of the new master since a large number of clients
|
||
may be attempting to communicate with and transfer records from the
|
||
master. Client applications wanting to delay client synchronization
|
||
should call the <a href="../api_reference/C/repconfig.html" class="olink">DB_ENV->rep_set_config()</a> method with the
|
||
<a href="../api_reference/C/repconfig.html#config_DB_REP_CONF_DELAYCLIENT" class="olink">DB_REP_CONF_DELAYCLIENT</a> flag. The application will be
|
||
notified of the establishment of the new master as usual, but the
|
||
client will not proceed to synchronize with the new master.</p>
|
||
<p>Applications learn of a new master via the
|
||
<a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_NEWMASTER" class="olink">DB_EVENT_REP_NEWMASTER</a> event.</p>
|
||
<p>Client applications choosing to delay synchronization in this manner are
|
||
responsible for synchronizing the client environment at some future time
|
||
using the <a href="../api_reference/C/repsync.html" class="olink">DB_ENV->rep_sync()</a> method.</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="rep_c2c_sync"></a>Client-to-client synchronization</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>Instead of synchronizing with the new master, it is sometimes possible
|
||
for a client to synchronize with another client. Berkeley DB initiates
|
||
synchronization at the client by sending a request message via the
|
||
transport call-back function of the communication infrastructure. The
|
||
message is destined for the master site, but is also marked with a
|
||
<a href="../api_reference/C/reptransport.html#transport_DB_REP_ANYWHERE" class="olink">DB_REP_ANYWHERE</a> flag. The application may choose to send such
|
||
a request to another client, or to ignore the flag, sending it to its
|
||
indicated destination.</p>
|
||
<p>Furthermore, when the other client receives such a request it may be
|
||
unable to satisfy it. In this case it will reply to the requesting
|
||
client, telling it that it is unable to provide the requested
|
||
information. The requesting client will then re-issue the request.
|
||
Additionally, if the original request never reaches the other client,
|
||
the requesting client will again re-issue the request. In either of
|
||
these cases the message will be marked with the <a href="../api_reference/C/reptransport.html#transport_DB_REP_REREQUEST" class="olink">DB_REP_REREQUEST</a>
|
||
flag. The application may continue trying to find another client to
|
||
service the request, or it may give up and simply send it to the master
|
||
(that is, the environment ID explicitly specified to the transport
|
||
function).</p>
|
||
<p>
|
||
Replication Manager allows an application to designate one or more
|
||
remote sites (called its "peers") to receive client-to-client requests.
|
||
You do this by setting the <code class="literal">DB_REPMGR_PEER</code> parameter
|
||
using the <a href="../api_reference/C/dbsite_set_config.html" class="olink">DB_SITE->set_config()</a> method. Replication Manager always tries
|
||
to send requests marked with the <a href="../api_reference/C/reptransport.html#transport_DB_REP_ANYWHERE" class="olink">DB_REP_ANYWHERE</a> flag to a peer, if
|
||
available. However, it always sends a <a href="../api_reference/C/reptransport.html#transport_DB_REP_REREQUEST" class="olink">DB_REP_REREQUEST</a> to the master
|
||
site.
|
||
</p>
|
||
<p>Base API applications have complete freedom
|
||
in choosing where to send these <a href="../api_reference/C/reptransport.html#transport_DB_REP_ANYWHERE" class="olink">DB_REP_ANYWHERE</a> requests, and
|
||
in deciding how to handle <a href="../api_reference/C/reptransport.html#transport_DB_REP_REREQUEST" class="olink">DB_REP_REREQUEST</a>.</p>
|
||
<p>The delayed synchronization and client-to-client synchronization
|
||
features allow applications to do load balancing within replication
|
||
groups. For example, consider a replication group with 5 sites, A, B,
|
||
C, D and E. Site E just crashed, and site A was elected master. Sites
|
||
C and D have been configured for delayed synchronization. When site B
|
||
is notified that site A is a new master, it immediately synchronizes.
|
||
When B finishes synchronizing with the master, the application calls the
|
||
<a href="../api_reference/C/repsync.html" class="olink">DB_ENV->rep_sync()</a> method on sites C and D to cause them to synchronize as well.
|
||
Sites C and D (and E, when it has finished rebooting) can send their
|
||
requests to site B, and B then bears the brunt of the work and
|
||
network traffic for synchronization, making master site A available to
|
||
handle the normal application load and any write requests paused by
|
||
the election.</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="idp2309616"></a>Blocked client operations</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>Clients in the process of synchronizing with the master block access to
|
||
Berkeley DB operations during some parts of that process.
|
||
By default, most Berkeley DB methods will block until
|
||
client synchronization is complete, and then the method call proceeds.</p>
|
||
<p>Client applications which cannot wait and would prefer an immediate
|
||
error return instead of blocking, should call the
|
||
<a href="../api_reference/C/repconfig.html" class="olink">DB_ENV->rep_set_config()</a> method with the <a href="../api_reference/C/repconfig.html#config_DB_REP_CONF_NOWAIT" class="olink">DB_REP_CONF_NOWAIT</a> flag. This
|
||
configuration causes <a href="../api_reference/C/db.html" class="olink">DB</a> method calls to immediately return a
|
||
<a href="../api_reference/C/dbput.html#dbput_DB_REP_LOCKOUT" class="olink">DB_REP_LOCKOUT</a> error instead of blocking, if the client is
|
||
currently synchronizing with the master.</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="idp2331664"></a>Clients too far out-of-date to synchronize</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>Clients attempting to synchronize with the master may discover that
|
||
synchronization is not possible because the client no longer has any
|
||
overlapping information with the master site. By default, the master and
|
||
client automatically detect this state and perform an internal initialization
|
||
of the client. Because internal initialization requires transfer of
|
||
entire databases to the client, it can take a relatively long period of
|
||
time and may require database handles to be reopened in the client
|
||
applications.</p>
|
||
<p>Client applications which cannot wait or would prefer
|
||
to do a hot backup instead of performing internal initialization, should
|
||
call the <a href="../api_reference/C/repconfig.html" class="olink">DB_ENV->rep_set_config()</a> method to turn off the <a href="../api_reference/C/repconfig.html#config_DB_REP_CONF_AUTOINIT" class="olink">DB_REP_CONF_AUTOINIT</a> flag.
|
||
Turning off this configuration flag causes Berkeley DB to return
|
||
<a href="../api_reference/C/repmessage.html#repmsg_DB_REP_JOIN_FAILURE" class="olink">DB_REP_JOIN_FAILURE</a> to the application instead of performing
|
||
internal initialization.</p>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="rep_elect.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="rep.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="rep_init.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Elections </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Initializing a new site</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|