<?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>Ex_rep_base: a TCP/IP based communication infrastructure</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_ex.html" title="Ex_rep: a replication example" />
<link rel="next" href="rep_ex_rq.html" title="Ex_rep_base: putting it all together" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Ex_rep_base: a TCP/IP based communication infrastructure</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="rep_ex.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_ex_rq.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_ex_comm"></a>Ex_rep_base: a TCP/IP based communication infrastructure</h2>
</div>
</div>
</div>
<p>
Base API applications must implement a
communication infrastructure. The communication infrastructure
consists of three parts: a way to map environment IDs to particular
sites, the functions to get and receive messages, and the application
architecture that supports the particular communication infrastructure
used (for example, individual threads per communicating site, a shared
message handler for all sites, a hybrid solution). The communication
infrastructure for ex_rep_base is implemented in the file
<code class="filename">ex_rep/base/rep_net.c</code>, and each part of that infrastructure
is described as follows.</p>
<p>Ex_rep_base maintains a table of environment ID to TCP/IP port
mappings. A pointer to this table is stored in a structure pointed to
by the app_private field of the <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> object so it can be
accessed by any function that has the database environment handle.
The table is represented by a machtab_t structure which contains a
reference to a linked list of member_t's, both of which are defined in
<code class="filename">ex_rep/base/rep_net.c</code>. Each member_t contains the host and
port identification, the environment ID, and a file descriptor.</p>
<p>This design is particular to this application and communication
infrastructure, but provides an indication of the sort of functionality
that is needed to maintain the application-specific state for a
TCP/IP-based infrastructure. The goal of the table and its interfaces
is threefold: First, it must guarantee that given an environment ID,
the send function can send a message to the appropriate place. Second,
when given the special environment ID <a href="../api_reference/C/reptransport.html#transport_DB_EID_BROADCAST" class="olink">DB_EID_BROADCAST</a>, the send
function can send messages to all the machines in the group. Third,
upon receipt of an incoming message, the receive function can correctly
identify the sender and pass the appropriate environment ID to the
<a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> method.</p>
<p>Mapping a particular environment ID to a specific port is accomplished
by looping through the linked list until the desired environment ID is
found. Broadcast communication is implemented by looping through the
linked list and sending to each member found. Since each port
communicates with only a single other environment, receipt of a message
on a particular port precisely identifies the sender.</p>
<p>This is implemented in the quote_send, quote_send_broadcast and
quote_send_one functions, which can be found in
<code class="filename">ex_rep/base/rep_net.c</code>.</p>
<p>The example provided is merely one way to satisfy these requirements,
and there are alternative implementations as well. For instance,
instead of associating separate socket connections with each remote
environment, an application might instead label each message with a
sender identifier; instead of looping through a table and sending a
copy of a message to each member of the replication group, the
application could send a single message using a broadcast protocol.</p>
<p>The quote_send function is passed as the callback to
<a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a>; Berkeley DB automatically sends messages as needed
for replication. The receive function is a mirror to the quote_send_one
function. It is not a callback function (the application is responsible
for collecting messages and calling <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a> on them as is
convenient). In the sample application, all messages transmitted are
Berkeley DB messages that get handled by <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a>, however, this
is not always going to be the case. The application may want to pass
its own messages across the same channels, distinguish between its own
messages and those of Berkeley DB, and then pass only the Berkeley DB ones to
<a href="../api_reference/C/repmessage.html" class="olink">DB_ENV->rep_process_message()</a>.</p>
<p>The final component of the communication infrastructure is the process
model used to communicate with all the sites in the replication group.
Each site creates a thread of control that listens on its designated
socket (as specified by the <span class="bold"><strong>-l</strong></span> command line argument) and
then creates a new channel for each site that contacts it. In addition,
each site explicitly connects to the sites specified in the
<span class="bold"><strong>-r</strong></span> and <span class="bold"><strong>-R</strong></span>
command line arguments. This is a fairly standard TCP/IP
process architecture and is implemented by the connect_thread,
connect_all and connect_site functions
in <code class="filename">ex_rep/base/rep_msg.c</code> and supporting functions
in <code class="filename">ex_rep/base/rep_net.c</code>.</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="rep_ex.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_ex_rq.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Ex_rep: a replication example </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Ex_rep_base: putting it all together</td>
</tr>
</table>
</div>
</body>
</html>
