diff options
Diffstat (limited to 'docs/programmer_reference/rep_app.html')
| -rw-r--r-- | docs/programmer_reference/rep_app.html | 224 |
1 files changed, 129 insertions, 95 deletions
diff --git a/docs/programmer_reference/rep_app.html b/docs/programmer_reference/rep_app.html index 71578840..a8dba30e 100644 --- a/docs/programmer_reference/rep_app.html +++ b/docs/programmer_reference/rep_app.html @@ -14,7 +14,7 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> @@ -22,9 +22,7 @@ </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="rep_pri.html">Prev</a> </td> - <th width="60%" align="center">Chapter 12. - Berkeley DB Replication - </th> + <th width="60%" align="center">Chapter 12. Berkeley DB Replication </th> <td width="20%" align="right"> <a accesskey="n" href="rep_mgr_meth.html">Next</a></td> </tr> </table> @@ -38,98 +36,134 @@ </div> </div> </div> - <p>The simplest way to build a replicated Berkeley DB application is to first -build (and debug!) the transactional version of the same application. -Then, add a thin replication layer: application initialization must be -changed and the application's communication infrastructure must be -added.</p> - <p>The application initialization changes are relatively simple. -Replication Manager provides a communication infrastructure, but -in order to use the replication Base APIs you must provide your own.</p> - <p>For implementation reasons, all replicated databases must reside in -the data directories set from <a href="../api_reference/C/envset_data_dir.html" class="olink">DB_ENV->set_data_dir()</a> (or in the -default environment home directory, if not using -<a href="../api_reference/C/envset_data_dir.html" class="olink">DB_ENV->set_data_dir()</a>), rather than in a subdirectory below the -specified directory. Care must be taken in applications using -relative pathnames and changing working directories after opening the -environment. In such applications the replication initialization code -may not be able to locate the databases, and applications that change -their working directories may need to use absolute pathnames.</p> - <p>During application initialization, the application performs -three additional tasks: first, it must specify the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_REP" class="olink">DB_INIT_REP</a> -flag when opening its database environment and additionally, a -Replication Manager application must also specify the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag; -second, it must provide Berkeley DB information about its communications -infrastructure; and third, it must start the Berkeley DB replication system. -Generally, a replicated application will do normal Berkeley DB recovery and -configuration, exactly like any other transactional application.</p> <p> - Replication Manager applications configure the built-in communications - infrastructure by calling obtaining a <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a> handle, and then using - it to configure the local site. It can optionally obtain one or more - <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a> handles to configure remote sites. Once the environment has - been opened, the application starts the replication system by calling - the <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a> method. -</p> - <p>A Base API application calls the -<a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> method to configure the entry point to its own -communications infrastructure, and then calls the -<a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> method to join or create the replication group.</p> - <p>When starting the replication system, an application has two choices: -it may choose the group master site explicitly, or alternatively it -may configure all group members as clients and then call for an -election, letting the clients select the master from among -themselves. Either is correct, and the choice is entirely up to the -application.</p> - <p>Replication Manager applications make this choice simply by setting -the flags parameter to the <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a> method.</p> - <p>For a Base API application, the result of -calling <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> is usually the discovery of a master, or the -declaration of the local environment as the master. If a master has -not been discovered after a reasonable amount of time, the application -should call <a href="../api_reference/C/repelect.html" class="olink">DB_ENV->rep_elect()</a> to call for an election.</p> - <p>Consider a Base API application with multiple processes or multiple -environment handles -that modify databases in the replicated environment. All modifications -must be done on the master environment. The first process to join or -create the master environment must call both the -<a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> and the <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> method. Subsequent -replication processes must at least call the <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> method. -Those processes may call the <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> method (as long as they use the -same master or client argument). If multiple processes are modifying -the master environment there must be a unified communication -infrastructure such that messages arriving at clients have a single -master ID. Additionally the application must be structured so that all -incoming messages are able to be processed by a single <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> -handle.</p> - <p>Note that not all processes running in replicated environments need to -call <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a>, <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> or <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a>. Read-only -processes running in a master environment do not need to be configured -for replication in any way. Processes running in a client environment -are read-only by definition, and so do not need to be configured for -replication either (although, in the case of clients that may become -masters, it is usually simplest to configure for replication on process -startup rather than trying to reconfigure when the client becomes a -master). Obviously, at least one thread of control on each client must -be configured for replication as messages must be passed between the -master and the client.</p> - <p>Any site in a replication group may have its own private -transactional databases in the environment as well. A site may -create a local database by specifying the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_TXN_NOT_DURABLE" class="olink">DB_TXN_NOT_DURABLE</a> -flag to the <a href="../api_reference/C/dbset_flags.html" class="olink">DB->set_flags()</a> method. The application -must never create a private database with the same name -as a database replicated across the entire environment -as data corruption can result.</p> - <p>For implementation reasons, Base API applications must process -all incoming replication messages -using the same <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handle. It is not required that -a single thread of control process all messages, only that all threads -of control processing messages use the same handle.</p> - <p>No additional calls are required to shut down a database environment -participating in a replication group. The application should shut down -the environment in the usual manner, by calling the <a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a> method. -For Replication Manager applications, this also terminates all network -connections and background processing threads.</p> + The simplest way to build a replicated Berkeley DB + application is to first build (and debug!) the transactional + version of the same application. Then, add a thin replication + layer: application initialization must be changed and the + application's communication infrastructure must be + added. + </p> + <p> + The application initialization changes are relatively + simple. Replication Manager provides a communication + infrastructure, but in order to use the replication Base APIs + you must provide your own. + </p> + <p> + For implementation reasons, all replicated databases must + reside in the data directories set from <a href="../api_reference/C/envadd_data_dir.html" class="olink">DB_ENV->add_data_dir()</a> (or + in the default environment home directory, if not using + <a href="../api_reference/C/envadd_data_dir.html" class="olink">DB_ENV->add_data_dir()</a>), rather than in a subdirectory below the + specified directory. Care must be taken in applications using + relative pathnames and changing working directories after + opening the environment. In such applications the replication + initialization code may not be able to locate the databases, + and applications that change their working directories may + need to use absolute pathnames. + </p> + <p> + During application initialization, the application performs + three additional tasks: first, it must specify the + <a href="../api_reference/C/envopen.html#envopen_DB_INIT_REP" class="olink">DB_INIT_REP</a> flag when opening its database environment and + additionally, a Replication Manager application must also + specify the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag; second, it must provide Berkeley + DB information about its communications infrastructure; and + third, it must start the Berkeley DB replication system. + Generally, a replicated application will do normal Berkeley DB + recovery and configuration, exactly like any other + transactional application. + </p> + <p> + Replication Manager applications configure the built-in + communications infrastructure by calling obtaining a <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a> + handle, and then using it to configure the local site. It can + optionally obtain one or more <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a> handles to configure + remote sites. Once the environment has been opened, the + application starts the replication system by calling the + <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a> method. + </p> + <p> + A Base API application calls the <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> method to + configure the entry point to its own communications + infrastructure, and then calls the <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> method to join + or create the replication group. + </p> + <p> + When starting the replication system, an application has two + choices: it may choose the group master site explicitly, or + alternatively it may configure all group members as clients + and then call for an election, letting the clients select the + master from among themselves. Either is correct, and the + choice is entirely up to the application. + </p> + <p> + Replication Manager applications make this choice simply by + setting the flags parameter to the <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a> + method. + </p> + <p> + For a Base API application, the result of calling <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> + is usually the discovery of a master, or the declaration of + the local environment as the master. If a master has not been + discovered after a reasonable amount of time, the application + should call <a href="../api_reference/C/repelect.html" class="olink">DB_ENV->rep_elect()</a> to call for an election. + </p> + <p> + Consider a Base API application with multiple processes or + multiple environment handles that modify databases in the + replicated environment. All modifications must be done on the + master environment. The first process to join or create the + master environment must call both the <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> and the + <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> method. Subsequent replication processes must at + least call the <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> method. Those processes may call + the <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a> method (as long as they use the same master or + client argument). If multiple processes are modifying the + master environment there must be a unified communication + infrastructure such that messages arriving at clients have a + single master ID. Additionally the application must be + structured so that all incoming messages are able to be + processed by a single <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handle. + </p> + <p> + Note that not all processes running in replicated + environments need to call <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV->repmgr_start()</a>, <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV->rep_set_transport()</a> or + <a href="../api_reference/C/repstart.html" class="olink">DB_ENV->rep_start()</a>. Read-only processes running in a master + environment do not need to be configured for replication in + any way. Processes running in a client environment are + read-only by definition, and so do not need to be configured + for replication either (although, in the case of clients that + may become masters, it is usually simplest to configure for + replication on process startup rather than trying to + reconfigure when the client becomes a master). Obviously, at + least one thread of control on each client must be configured + for replication as messages must be passed between the master + and the client. + </p> + <p> + Any site in a replication group may have its own private + transactional databases in the environment as well. A site may + create a local database by specifying the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_TXN_NOT_DURABLE" class="olink">DB_TXN_NOT_DURABLE</a> + flag to the <a href="../api_reference/C/dbset_flags.html" class="olink">DB->set_flags()</a> method. The application must never + create a private database with the same name as a database + replicated across the entire environment as data corruption + can result. + </p> + <p> + For implementation reasons, Base API applications must + process all incoming replication messages using the same <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> + handle. It is not required that a single thread of control + process all messages, only that all threads of control + processing messages use the same handle. + </p> + <p> + No additional calls are required to shut down a database + environment participating in a replication group. The + application should shut down the environment in the usual + manner, by calling the <a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a> method. For Replication + Manager applications, this also terminates all network + connections and background processing threads. + </p> </div> <div class="navfooter"> <hr /> |