mirror of
https://github.com/yasuhirokimura/db18
synced 2026-06-08 18:29:23 +00:00
Yasuhiro KIMURA
382 lines
18 KiB
HTML
382 lines
18 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>Communicating between Replication Manager Sites</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_clock_skew.html" title="Clock skew" />
|
||
<link rel="next" href="rep_twosite.html" title="Special considerations for two-site replication groups" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 18.1.40</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Communicating between Replication Manager Sites</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="rep_clock_skew.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_twosite.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="comm_repsites"></a>Communicating between Replication Manager Sites</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="toc">
|
||
<dl>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="comm_repsites.html#conf_writeforw">Configuring for Write Forwarding</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="comm_repsites.html#repmgr_channels">Using Replication Manager message channels</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
Replication Manager provides all of the communications between sites needed for
|
||
an application that performs all of its write operations on the master site and
|
||
only performs read operations on client sites.
|
||
</p>
|
||
<p>
|
||
For applications with a simple data and transaction model, Replication Manager
|
||
also provides automatic write forwarding as a configurable option. When write
|
||
forwarding is configured, some write operations can be performed on clients.
|
||
In addition, an application can use Replication Manager message channels to
|
||
send its own messages to other sites in the replication group using Replication
|
||
Manager's internal communications infrastructure.
|
||
</p>
|
||
<p>
|
||
These approaches are described in the following sections.
|
||
</p>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="conf_writeforw"></a>Configuring for Write Forwarding</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
By default, write operations cannot be performed on a
|
||
replication client site. Replication Manager provides a configurable
|
||
option that allows forwarding of simple client put and delete
|
||
operations to the master site for processing. These operations must
|
||
use an implicit NULL transaction ID to be forwarded. Any other write
|
||
operation that specifies a non-NULL transaction or uses a cursor
|
||
returns an error. This option is turned off by default.
|
||
</p>
|
||
<p>
|
||
To configure write forwarding, use
|
||
<code class="function">rep_set_config</code> with the
|
||
<code class="literal">DB_REPMGR_CONF_FORWARD_WRITES</code> option.
|
||
(See the <a href="../api_reference/C/repconfig.html#config_DB_REPMGR_CONF_FORWARD_WRITES" class="olink">
|
||
DB_REPMGR_CONF_FORWARD_WRITES</a> section in the <em class="citetitle">Berkeley DB C API Reference Guide</em>
|
||
for more information.)
|
||
</p>
|
||
<p>
|
||
The master must have an open database handle for the database
|
||
on which a forwarded write operation is being performed.
|
||
All sites in the replication group should have the same value
|
||
for this configuration option.
|
||
</p>
|
||
<p>
|
||
The following restrictions apply to the use of write forwarding:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
The application cannot use Replication Manager message channels for any other purpose.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
All sites in the replication group must be on platforms of the same endianness.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Write forwarding cannot be performed on databases using callbacks
|
||
or values that must be supplied for each <code class="methodname">DbEnv::open()</code>
|
||
call to avoid database corruption. Examples include the callbacks or
|
||
values defined by the <code class="methodname">DB->set_dup_compare()</code>,
|
||
<code class="methodname">DB->set_bt_compare()</code>,
|
||
<code class="methodname">DB->set_hash()</code> and
|
||
<code class="methodname">DB->set_heapsize() methods</code>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Write forwarding cannot be performed on a partitioned database.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Bulk put and del operations using <code class="literal">DB_MULTIPLE</code> or
|
||
<code class="literal">DB_MULTIPLE_KEY</code> flags are not supported.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>
|
||
For more information, see <em class="citetitle">Berkeley DB Getting Started with Replicated Applications</em>.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="repmgr_channels"></a>Using Replication Manager message channels</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The various sites comprising a replication group frequently
|
||
need to communicate with one another. Mostly, these messages
|
||
are handled for you internally by the Replication Manager.
|
||
However, your application may have a requirement to pass
|
||
messages beyond what the Replication Manager requires in order
|
||
to satisfy its own internal workings.
|
||
</p>
|
||
<p>
|
||
For this reason, you can access and use the Replication
|
||
Manager's internal message channels. You do this by using the
|
||
<code class="literal">DB_CHANNEL</code> class, and by implementing a
|
||
message handling function on each of your sites.
|
||
</p>
|
||
<p>
|
||
Note that an example of using Replication Manager message
|
||
channels is available in the distribution. See <a class="xref" href="rep_ex_chan.html" title="Ex_rep_chan: a Replication Manager channel example">Ex_rep_chan: a Replication Manager channel example</a> for
|
||
more information.
|
||
</p>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="dbchannel_class"></a>DB_CHANNEL</h4>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The <code class="literal">DB_CHANNEL</code> class provides a
|
||
series of methods which allow you to send messages to the
|
||
other sites in your replication group. You create a
|
||
<code class="literal">DB_CHANNEL</code> handle using the
|
||
<a href="../api_reference/C/repmgr_channel.html" class="olink">DB_ENV->repmgr_channel()</a> method. When you are done with the
|
||
handle, close it using the <a href="../api_reference/C/dbchannel_close.html" class="olink">DB_CHANNEL->close()</a> method. A
|
||
closed handle must never be accessed again. Note that all
|
||
channel handles should be closed before the associated
|
||
environment handle is closed. Also, allow all message
|
||
operations to complete on the channel before closing the
|
||
handle.
|
||
</p>
|
||
<p>
|
||
When you create a <code class="literal">DB_CHANNEL</code> handle,
|
||
you indicate what channel you want to use. Possibilities
|
||
are:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
The numerical env ID of a remote site in the
|
||
replication group.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="literal">DB_EID_MASTER</code>
|
||
</p>
|
||
<p>
|
||
Messages sent on this channel are sent only to
|
||
the master site. Note that messages are always
|
||
sent to the current master, even if the master has
|
||
changed since the channel was opened.
|
||
</p>
|
||
<p>
|
||
If the local site is the master, then sending
|
||
messages on this channel will result in the local
|
||
site receiving those messages echoed back to
|
||
itself.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="dbchannel_send"></a>Sending messages over a message channel</h4>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
You can send any message you want over a message
|
||
channel. The message can be as simple as a character
|
||
string and as complex as a large data structure. However,
|
||
before you can send the message, you must encapsulate it
|
||
within one or more <a href="../api_reference/C/dbt.html" class="olink">DBT</a>s. This means <a class="link" href="am_misc_struct.html" title="Storing C/C++ structures/objects">marshaling the message</a>
|
||
if it is contained within a complex data structure. </p>
|
||
<p>
|
||
The methods that you use to send messages all accept an
|
||
array of <a href="../api_reference/C/dbt.html" class="olink">DBT</a>s. This means that in most circumstances it
|
||
is perfectly acceptable to send multi-part messages.
|
||
</p>
|
||
<p>
|
||
Messages may be sent either asynchronously or
|
||
synchronously. To send a message asynchronously, use the
|
||
<a href="../api_reference/C/dbchannel_send_msg.html" class="olink">DB_CHANNEL->send_msg()</a> method. This method sends its message
|
||
and then immediately returns without waiting for any sort
|
||
of a response.
|
||
|
||
</p>
|
||
<p>
|
||
To send a message synchronously, use the
|
||
<a href="../api_reference/C/dbchannel_send_request.html" class="olink">DB_CHANNEL->send_request()</a> method. This method blocks until
|
||
it receives a response from the site to which it sent the
|
||
message (or until a timeout threshold is reached).
|
||
|
||
</p>
|
||
</div>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="dbchannel_respond"></a>Message Responses</h4>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
Message responses are required if a message is sent
|
||
on a channel using the <a href="../api_reference/C/dbchannel_send_request.html" class="olink">DB_CHANNEL->send_request()</a>
|
||
method. That method accepts the address of a single
|
||
<a href="../api_reference/C/dbt.html" class="olink">DBT</a> which is used to receive the response from the
|
||
remote site.
|
||
</p>
|
||
<p>
|
||
Message responses are encapsulated in a single
|
||
<a href="../api_reference/C/dbt.html" class="olink">DBT</a>. The response can be anything from a complex
|
||
data structure, to a string, to a simple type, to no
|
||
information at all. In the latter case, receipt of the
|
||
<a href="../api_reference/C/dbt.html" class="olink">DBT</a> is sufficient to indicate that the request was
|
||
received at the remote site.
|
||
</p>
|
||
<p> Responses are sent back from the remote system
|
||
using its message handling function. Usually that
|
||
function calls <a href="../api_reference/C/dbchannel_send_msg.html" class="olink">DB_CHANNEL->send_msg()</a> to send a single
|
||
response. </p>
|
||
<p>
|
||
The response must be contained in a single <a href="../api_reference/C/dbt.html" class="olink">DBT</a>.
|
||
If a multi-part response is required by the
|
||
application, you can configure the response <a href="../api_reference/C/dbt.html" class="olink">DBT</a> that
|
||
you provide to <a href="../api_reference/C/dbchannel_send_request.html" class="olink">DB_CHANNEL->send_request()</a> for <a class="link" href="am_misc_bulk.html" title="Retrieving and updating records in bulk">bulk operations</a>.
|
||
</p>
|
||
</div>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="dbchannel_receive"></a>Receiving messages</h4>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
Messages received at a remote site are handled using a
|
||
callback function. This function is configured for the
|
||
local environment using the <a href="../api_reference/C/repmgr_msg_dispatch.html" class="olink">DB_ENV->repmgr_msg_dispatch()</a>
|
||
method. For best results, the message dispatch function
|
||
should be configured for the local environment before
|
||
replication is started. In this way, you do not run the
|
||
risk of missing messages sent after replication has
|
||
started but before the message dispatch function is
|
||
configured for the environment.
|
||
</p>
|
||
<p>
|
||
The callback configured by <a href="../api_reference/C/repmgr_msg_dispatch.html" class="olink">DB_ENV->repmgr_msg_dispatch()</a>
|
||
accepts four parameters of note:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
A response channel. This is the channel the
|
||
function will use to respond to the message, if a
|
||
response is required. To respond to the message,
|
||
the function uses the <a href="../api_reference/C/dbchannel_send_msg.html" class="olink">DB_CHANNEL->send_msg()</a> method.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
An array of <a href="../api_reference/C/dbt.html" class="olink">DBT</a>s. These hold the message that
|
||
this function must handle.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
A numerical value that indicates how many
|
||
elements the previously described array holds.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
A flag that indicates whether the message
|
||
requires a response. If the flag is set to
|
||
<code class="literal">DB_REPMGR_NEED_RESPONSE</code>,
|
||
then the function should send a single <a href="../api_reference/C/dbt.html" class="olink">DBT</a> in
|
||
response using the channel provided to this
|
||
function, and the <a href="../api_reference/C/dbchannel_send_msg.html" class="olink">DB_CHANNEL->send_msg()</a> method.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>
|
||
For an example of using this callback, see the
|
||
<code class="literal">operation_dispatch()</code> function,
|
||
which is available with the <a class="link" href="rep_ex_chan.html" title="Ex_rep_chan: a Replication Manager channel example">
|
||
ex_rep_chan example</a> in your product
|
||
distribution.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="rep_clock_skew.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_twosite.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Clock skew </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Special considerations for two-site replication groups</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|