diff options
Diffstat (limited to 'docs/programmer_reference/rep_mgr_ack.html')
| -rw-r--r-- | docs/programmer_reference/rep_mgr_ack.html | 186 |
1 files changed, 112 insertions, 74 deletions
diff --git a/docs/programmer_reference/rep_mgr_ack.html b/docs/programmer_reference/rep_mgr_ack.html index 9b9a847c..41d9e935 100644 --- a/docs/programmer_reference/rep_mgr_ack.html +++ b/docs/programmer_reference/rep_mgr_ack.html @@ -3,28 +3,26 @@ <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <title>Choosing a Replication Manager Ack Policy</title> + <title>Choosing a Replication Manager acknowledgement policy</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_replicate.html" title="Running Replication using the db_replicate Utility" /> + <link rel="prev" href="rep_replicate.html" title="Running replication using the db_replicate utility" /> <link rel="next" href="rep_elect.html" title="Elections" /> </head> <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">Choosing a Replication Manager Ack Policy</th> + <th colspan="3" align="center">Choosing a Replication Manager acknowledgement policy</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="rep_replicate.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_elect.html">Next</a></td> </tr> </table> @@ -34,75 +32,114 @@ <div class="titlepage"> <div> <div> - <h2 class="title" style="clear: both"><a id="rep_mgr_ack"></a>Choosing a Replication Manager Ack Policy</h2> + <h2 class="title" style="clear: both"><a id="rep_mgr_ack"></a>Choosing a Replication Manager acknowledgement policy</h2> </div> </div> </div> - <p>Replication Manager allows the user to choose from a variety of -acknowledgement policies. There are two characteristics that should -be considered when choosing the policy: consistency and durability. -Consistency means making sure some number of clients have applied -all available master transactions. Durability, in this context, -means only indicating success only if enough clients have -applied a transaction. The issue of how many is enough depends -on the application's requirements and varies per acknowledgement policy. -For example, <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_QUORUM" class="olink">DB_REPMGR_ACKS_QUORUM</a> means the data will survive -a change in master or a network partition. -In most cases, the number of sites for consistency is -equal to the number of sites for durability. Replication Manager -uses the consistency value to decide whether or not to wait for -acknowledgements. Replication manager uses the durability value -to decide either the transaction was successfully processed or that -a <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> event should be generated.</p> - <p>Replication Manager also strives to give the application the -answer and return to the application as quickly as possible. Therefore, -if it knows that the number of sites connected is insufficient to meet -the consistency value, then it does not wait for any acknowledgements -and if it knows that the durability value cannot be met, it returns -<a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> immediately to the user.</p> - <p>With one exception, discussed below, all acknowledgement policies combine -the consistency and durability values. For most policies the primary -purpose is the durability of the data. For example, the <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_QUORUM" class="olink">DB_REPMGR_ACKS_QUORUM</a> -policy ensures that, if successful, the transaction's data is safe in -the event of a network partition so that a majority of the sites in -the group have the data. The <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_NONE" class="olink">DB_REPMGR_ACKS_NONE</a> policy does not -consider either consistency or durability, and it is very -fast because it does not wait for any acknowledgements and it does not -ever trigger the <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> event. Other policies, -<a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL" class="olink">DB_REPMGR_ACKS_ALL</a> and <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_PEERS" class="olink">DB_REPMGR_ACKS_ALL_PEERS</a>, have a primary purpose of -consistency. These two policies wait for acknowledgements from all -(or all electable) sites in the group.</p> - <p>In the face of failure, however, the <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL" class="olink">DB_REPMGR_ACKS_ALL</a> and -<a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_PEERS" class="olink">DB_REPMGR_ACKS_ALL_PEERS</a> policies can result -in a surprising lack of consistency due to the fact that Replication Manager -strives to give the answer back to the application as fast as it can. -So, for example, with <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL" class="olink">DB_REPMGR_ACKS_ALL</a>, and one site down, Replication -Manager knows that disconnected site can never acknowledge, so it -immediately triggers <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a>. An unfortunate side -effect of this policy is that existing, running sites may fall further and -further behind the master if the master site is sending a fast, busy -stream of transactions and never waiting for any site to send an -acknowledgement. The master does not wait because the consistency -value cannot be met, and it does trigger the <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> -event because the durability value cannot be met, but those -actions now affect the consistency of the other running sites.</p> - <p>In order to counteract this unfortunate side effect, -the <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_AVAILABLE" class="olink">DB_REPMGR_ACKS_ALL_AVAILABLE</a> acknowledgement policy focuses on the -consistency aspect, but also considers durability. This policy -uses all sites for consistency, -and a quorum of sites for its decision about durability. As long -as there is a non-zero number of client replicas to send to, the -master will wait for all available sites to acknowledge the -transaction. As long as any client site is connected, this policy -will prevent the master from racing ahead if one or more sites is down. -On the master, this policy will then consider the transaction durable if -the number of acknowledgements meets quorum for the group.</p> - <p>The following acknowledgement policies determine durability -using acknowledgements from electable peers only: <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_QUORUM" class="olink">DB_REPMGR_ACKS_QUORUM</a>, -<a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ONE_PEER" class="olink">DB_REPMGR_ACKS_ONE_PEER</a>, <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_PEERS" class="olink">DB_REPMGR_ACKS_ALL_PEERS</a>. An electable -peer is a site where the priority value is greater than zero. In -replication groups using these policies, an unelectable site does not -send acknowledgements and cannot contribute to transaction durability.</p> + <p> + Replication Manager allows the user to choose from a variety + of acknowledgement policies. There are two characteristics + that should be considered when choosing the policy: + consistency and durability. Consistency means making sure some + number of clients have applied all available master + transactions. Durability, in this context, means only + indicating success only if enough clients have applied a + transaction. The issue of how many is enough depends on the + application's requirements and varies per acknowledgement + policy. For example, <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_QUORUM" class="olink">DB_REPMGR_ACKS_QUORUM</a> means the data + will survive a change in master or a network partition. In + most cases, the number of sites for consistency is equal to + the number of sites for durability. Replication Manager uses + the consistency value to decide whether or not to wait for + acknowledgements. Replication manager uses the durability + value to decide either the transaction was successfully + processed or that a <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> event should be + generated. + </p> + <p> + Replication Manager also strives to give the application the + answer and return to the application as quickly as possible. + Therefore, if it knows that the number of sites connected is + insufficient to meet the consistency value, then it does not + wait for any acknowledgements and if it knows that the + durability value cannot be met, it returns + <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> immediately to the user. + </p> + <p> + With one exception, discussed below, all acknowledgement + policies combine the consistency and durability values. For + most policies the primary purpose is the durability of the + data. For example, the <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_QUORUM" class="olink">DB_REPMGR_ACKS_QUORUM</a> policy ensures + that, if successful, the transaction's data is safe in the + event of a network partition so that a majority of the sites + in the group have the data. The <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_NONE" class="olink">DB_REPMGR_ACKS_NONE</a> policy + does not consider either consistency or durability, and it is + very fast because it does not wait for any acknowledgements + and it does not ever trigger the <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> + event. Other policies, <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL" class="olink">DB_REPMGR_ACKS_ALL</a> and + <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_PEERS" class="olink">DB_REPMGR_ACKS_ALL_PEERS</a>, have a primary purpose of + consistency. These two policies wait for acknowledgements from + all (or all electable) sites in the group. + </p> + <p> + In the face of failure, however, the <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL" class="olink">DB_REPMGR_ACKS_ALL</a> + and <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_PEERS" class="olink">DB_REPMGR_ACKS_ALL_PEERS</a> policies can result in a + surprising lack of consistency due to the fact that + Replication Manager strives to give the answer back to the + application as fast as it can. So, for example, with + <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL" class="olink">DB_REPMGR_ACKS_ALL</a>, and one site down, Replication Manager + knows that disconnected site can never acknowledge, so it + immediately triggers <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a>. An + unfortunate side effect of this policy is that existing, + running sites may fall further and further behind the master + if the master site is sending a fast, busy stream of + transactions and never waiting for any site to send an + acknowledgement. The master does not wait because the + consistency value cannot be met, and it does trigger the + <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> event because the durability value + cannot be met, but those actions now affect the consistency of + the other running sites. + </p> + <p> + In order to counteract this unfortunate side effect, the + <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_AVAILABLE" class="olink">DB_REPMGR_ACKS_ALL_AVAILABLE</a> acknowledgement policy focuses + on the consistency aspect, but also considers durability. This + policy uses all sites for consistency, and a quorum of sites + for its decision about durability. As long as there is a + non-zero number of client replicas to send to, the master will + wait for all available sites to acknowledge the transaction. + As long as any client site is connected, this policy will + prevent the master from racing ahead if one or more sites is + down. On the master, this policy will then consider the + transaction durable if the number of acknowledgements meets + quorum for the group. + </p> + <p> + The following acknowledgement policies determine durability + using acknowledgements from electable peers only: + <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_QUORUM" class="olink">DB_REPMGR_ACKS_QUORUM</a>, <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ONE_PEER" class="olink">DB_REPMGR_ACKS_ONE_PEER</a>, + <a href="../api_reference/C/repmgrset_ack_policy.html#ackspolicy_DB_REPMGR_ACKS_ALL_PEERS" class="olink">DB_REPMGR_ACKS_ALL_PEERS</a>. An electable peer is a site where + the priority value is greater than zero. In replication groups + using these policies, an unelectable site does not send + acknowledgements and cannot contribute to transaction + durability. + </p> + <p> + If your application needs to associate a <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> + event with the specific transaction and thread that caused it, + this can be done by using your platform's thread-specific data + facility. You can create a thread-specific data structure that + contains a durability indicator. You would set the durability + indicator in the <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> portion of your event + notification callback function. You can then check and clear the + durability indicator after your transaction commit operation + completes. You must be careful to coordinate this approach across + all application threads performing transaction commits or checkpoints + because any of these threads can generate a <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_REP_PERM_FAILED" class="olink">DB_EVENT_REP_PERM_FAILED</a> + event. The ex_rep_mgr sample application demonstrates one way to + implement this capability. See + <a class="xref" href="rep_ex.html" title="Ex_rep: a replication example">Ex_rep: a replication example</a> for more information. + </p> </div> <div class="navfooter"> <hr /> @@ -115,7 +152,8 @@ send acknowledgements and cannot contribute to transaction durability.</p> <td width="40%" align="right"> <a accesskey="n" href="rep_elect.html">Next</a></td> </tr> <tr> - <td width="40%" align="left" valign="top">Running Replication using the db_replicate Utility </td> + <td width="40%" align="left" valign="top">Running replication using the + db_replicate utility </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> |