<?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>Running Replication Manager in multiple processes</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_newsite.html" title="Connecting to a new site" /> <link rel="next" href="rep_replicate.html" title="Running Replication using the db_replicate Utility" /> </head> <body> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center">Running Replication Manager in multiple processes</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="rep_newsite.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_replicate.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_mgrmulti"></a>Running Replication Manager in multiple processes</h2> </div> </div> </div> <div class="toc"> <dl> <dt> <span class="sect2"> <a href="rep_mgrmulti.html#id3868223">One replication process and multiple subordinate processes</a> </span> </dt> <dt> <span class="sect2"> <a href="rep_mgrmulti.html#id3867832">Persistence of network address configuration</a> </span> </dt> <dt> <span class="sect2"> <a href="rep_mgrmulti.html#id3867886">Programming considerations</a> </span> </dt> <dt> <span class="sect2"> <a href="rep_mgrmulti.html#id3868016">Handling failure</a> </span> </dt> <dt> <span class="sect2"> <a href="rep_mgrmulti.html#id3868273">Other miscellaneous rules</a> </span> </dt> </dl> </div> <p>Replication Manager supports shared access to a database environment from multiple processes.</p> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="id3868223"></a>One replication process and multiple subordinate processes</h3> </div> </div> </div> <p>Each site in a replication group has just one network address (TCP/IP host name and port number). This means that only one process can accept incoming connections. At least one application process must invoke the <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a> method to initiate communications and management of the replication state.</p> <p>If it is convenient, multiple processes may issue calls to the Replication Manager configuration methods, and multiple processes may call <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a>. Replication Manager automatically opens the TCP/IP listening socket in the first process to do so (we'll call it the "replication process" here), and ignores this step in any subsequent processes ("subordinate processes").</p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="id3867832"></a>Persistence of network address configuration</h3> </div> </div> </div> <p>Local and remote site network addresses are stored in shared memory, and remain intact even when (all) processes close their environment handles gracefully and terminate. A process which opens an environment handle without running recovery automatically inherits all existing network address configuration. Such a process may not change the local site address (although it is allowed to make a redundant call to repmgr_set_local_site() specifying a configuration matching that which is already in effect).</p> <p>Similarly, removing an existing remote site address from an intact environment is currently not supported. In order to make either of these types of change, the application must run recovery. By doing so you start fresh with a clean slate, erasing all network address configuration information.</p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="id3867886"></a>Programming considerations</h3> </div> </div> </div> <p>Note that Replication Manager applications must follow all the usual rules for Berkeley DB multi-threaded and/or multi-process applications, such as ensuring that the recovery operation occurs single-threaded, only once, before any other thread or processes operate in the environment. Since Replication Manager creates its own background threads which operate on the environment, all environment handles must be opened with the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag, even if the application is otherwise single-threaded per process.</p> <p>At the replication master site, each Replication Manager process opens outgoing TCP/IP connections to all clients in the replication group. It uses these direct connections to send to clients any log records resulting from update transactions that the process executes. But all other replication activity —message processing, elections, etc.— takes place only in the replication process.</p> <p>Replication Manager notifies the application of certain events, using the callback function configured with the <a href="../api_reference/C/envevent_notify.html" class="olink">DB_ENV->set_event_notify()</a> method. These notifications occur only in the process where the event itself occurred. Generally this means that most notifications occur only in the "replication process". Currently the only replication notification that can occur in a "subordinate process" is <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a>.</p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="id3868016"></a>Handling failure</h3> </div> </div> </div> <p>Multi-process Replication Manager applications should handle failures in a manner consistent with the rules described in <a class="xref" href="transapp_fail.html" title="Handling failure in Transactional Data Store applications">Handling failure in Transactional Data Store applications</a>. To summarize, there are two ways to handle failure of a process:</p> <div class="orderedlist"> <ol type="1"> <li> <p> The simple way is to kill all remaining processes, run recovery, and then restart all processes from the beginning. But this can be a bit drastic. </p> </li> <li> <p> Using the <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method, it is sometimes possible to leave surviving processes running, and just restart the failed process. </p> <p> Multi-process Replication Manager applications using this technique must start a new process when an old process fails. It is not possible for a "subordinate process" to take over the duties of a failed "replication process". If the failed process happens to be the replication process, then after a failchk() call the next process to call <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a> will become the new replication process. </p> </li> </ol> </div> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="id3868273"></a>Other miscellaneous rules</h3> </div> </div> </div> <div class="orderedlist"> <ol type="1"> <li>A database environment may not be shared between a Replication Manager application process and a Base API application process.</li> <li>It is not possible to run multiple Replication Manager processes during mixed-version live upgrades from Berkeley DB versions prior to 4.8.</li> </ol> </div> </div> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="rep_newsite.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_replicate.html">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top">Connecting to a new site </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> <td width="40%" align="right" valign="top"> Running Replication using the db_replicate Utility</td> </tr> </table> </div> </body> </html>