diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2015-02-17 17:25:57 +0000 |
|---|---|---|
| committer | <> | 2015-03-17 16:26:24 +0000 |
| commit | 780b92ada9afcf1d58085a83a0b9e6bc982203d1 (patch) | |
| tree | 598f8b9fa431b228d29897e798de4ac0c1d3d970 /docs/programmer_reference/rep_mastersync.html | |
| parent | 7a2660ba9cc2dc03a69ddfcfd95369395cc87444 (diff) | |
| download | berkeleydb-master.tar.gz | |
Diffstat (limited to 'docs/programmer_reference/rep_mastersync.html')
| -rw-r--r-- | docs/programmer_reference/rep_mastersync.html | 240 |
1 files changed, 143 insertions, 97 deletions
diff --git a/docs/programmer_reference/rep_mastersync.html b/docs/programmer_reference/rep_mastersync.html index 203b61aa..05506c54 100644 --- a/docs/programmer_reference/rep_mastersync.html +++ b/docs/programmer_reference/rep_mastersync.html @@ -14,17 +14,16 @@ <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> - <th colspan="3" align="center">Synchronizing with a master</th> + <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> + <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> @@ -34,7 +33,8 @@ <div class="titlepage"> <div> <div> - <h2 class="title" style="clear: both"><a id="rep_mastersync"></a>Synchronizing with a master</h2> + <h2 class="title" style="clear: both"><a id="rep_mastersync"></a>Synchronizing with a + master</h2> </div> </div> </div> @@ -52,21 +52,25 @@ </dt> <dt> <span class="sect2"> - <a href="rep_mastersync.html#idp2309616">Blocked client operations</a> + <a href="rep_mastersync.html#idp1985136">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> + <a href="rep_mastersync.html#idp2008240">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> + <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> @@ -75,21 +79,30 @@ controls an application can use to reduce the synchronization burden.</p> </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> + <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"> @@ -99,92 +112,125 @@ using the <a href="../api_reference/C/repsync.html" class="olink">DB_ENV->rep </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> + 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, a + <a href="../api_reference/C/reptransport.html#transport_DB_REP_REREQUEST" class="olink">DB_REP_REREQUEST</a> message is always handled by requesting + the information from the master. A view can serve as a + peer, but a partial view is more likely to be missing + requested information, which will then be requested from + the master. + </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> + <h3 class="title"><a id="idp1985136"></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> + <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> + <h3 class="title"><a id="idp2008240"></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> + <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"> |