1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Permanent Message Handling</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Getting Started with Replicated Berkeley DB Applications" /> 10 <link rel="up" href="repapp.html" title="Chapter��3.��The DB Replication Manager" /> 11 <link rel="prev" href="repmgr_init_example_c.html" title="Adding the Replication Manager to ex_rep_gsg_simple" /> 12 <link rel="next" href="electiontimes.html" title="Managing Election Times" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Permanent Message Handling</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��3.��The DB Replication Manager</th> 23 <td width="20%" align="right">��<a accesskey="n" href="electiontimes.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="fwrkpermmessage"></a>Permanent Message Handling</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <dl> 38 <dt> 39 <span class="sect2"> 40 <a href="fwrkpermmessage.html#fmwrkpermpolicy">Identifying Permanent Message Policies</a> 41 </span> 42 </dt> 43 <dt> 44 <span class="sect2"> 45 <a href="fwrkpermmessage.html#fmwrkpermtimeout">Setting the Permanent Message Timeout</a> 46 </span> 47 </dt> 48 <dt> 49 <span class="sect2"> 50 <a href="fwrkpermmessage.html#perm2fmwrkexample">Adding a Permanent Message Policy to 51 <span>ex_rep_gsg_repmgr</span> 52 53 54 </a> 55 </span> 56 </dt> 57 </dl> 58 </div> 59 <p> 60 As described in <a class="xref" href="permmessages.html" title="Permanent Message Handling">Permanent Message Handling</a>, 61 messages are marked permanent if they contain database 62 modifications that should be committed at the replica. 63 DB's replication code decides if it must flush its 64 transaction logs to disk depending on whether it receives 65 sufficient permanent message acknowledgments from the 66 participating replicas. More importantly, the thread 67 performing the transaction commit blocks 68 until it either receives enough acknowledgments, or the 69 acknowledgment timeout expires. 70 </p> 71 <p> 72 The Replication Manager is fully capable of managing permanent messages 73 for you if your application requires it (most do). 74 Almost all of the details of this are handled by the 75 Replication Manager for you. However, you do have to set some policies 76 that tell the Replication Manager how to handle permanent messages. 77 </p> 78 <p> 79 There are two things that you have to do: 80 </p> 81 <div class="itemizedlist"> 82 <ul type="disc"> 83 <li> 84 <p> 85 Determine how many acknowledgments 86 must be received by the master. 87 </p> 88 </li> 89 <li> 90 <p> 91 Identify the amount of time that 92 replicas have to send their 93 acknowledgments. 94 </p> 95 </li> 96 </ul> 97 </div> 98 <div class="sect2" lang="en" xml:lang="en"> 99 <div class="titlepage"> 100 <div> 101 <div> 102 <h3 class="title"><a id="fmwrkpermpolicy"></a>Identifying Permanent Message Policies</h3> 103 </div> 104 </div> 105 </div> 106 <p> 107 108 You identify permanent message policies using the 109 <span> 110 <code class="methodname">DB_ENV->repmgr_set_ack_policy()</code> 111 112 method. 113 </span> 114 115 116 117 Note that you can set permanent message 118 policies at any time during the life of the 119 application. 120 </p> 121 <p> 122 The following permanent message policies are available when you use 123 the Replication Manager: 124</p> 125 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 126 <h3 class="title">Note</h3> 127 <p> 128 The following list mentions <span class="emphasis"><em>electable peer</em></span> 129 several times. This is simply another environment that can be 130 elected to be a master (that is, it has a priority greater than 0). 131 Do not confuse this with the concept of a peer as used for client 132 to client transfers. See <a class="xref" href="c2ctransfer.html" title="Client to Client Transfer">Client to Client Transfer</a> for more information on client 133 to client transfers. 134 </p> 135 </div> 136 <div class="itemizedlist"> 137 <ul type="disc"> 138 <li> 139 <p> 140 <code class="literal">DB_REPMGR_ACKS_NONE</code> 141 142 </p> 143 <p> 144 No permanent message acknowledgments are required. If 145 this policy is selected, permanent message handling is 146 essentially "turned off." That is, the master will 147 never wait for replica acknowledgments. In this case, 148 transaction log data is either flushed or not strictly 149 depending on the type of commit that is being performed 150 (synchronous or asynchronous). 151 </p> 152 </li> 153 <li> 154 <p> 155 <code class="literal">DB_REPMGR_ACKS_ONE</code> 156 157 </p> 158 <p> 159 At least one replica must acknowledge the permanent 160 message within the timeout period. 161 </p> 162 </li> 163 <li> 164 <p> 165 <code class="literal">DB_REPMGR_ACKS_ONE_PEER</code> 166 167 </p> 168 <p> 169 At least one electable peer must acknowledge the permanent 170 message within the timeout period. 171 </p> 172 </li> 173 <li> 174 <p> 175 <code class="literal">DB_REPMGR_ACKS_ALL</code> 176 177 </p> 178 <p> 179 All replicas must acknowledge the message within 180 the timeout period. This 181 policy should be selected only if your replication 182 group has a small number of replicas, and those replicas 183 are on extremely reliable networks and servers. 184 </p> 185 <p> 186 When this flag is used, the actual number of 187 replicas that must respond is 188 determined by the value set for 189 <span><code class="methodname">DB_ENV->rep_set_nsites()</code>.</span> 190 191 192 </p> 193 </li> 194 <li> 195 <p> 196 <code class="literal">DB_REPMGR_ACKS_ALL_PEERS</code> 197 198 </p> 199 <p> 200 All electable peers must acknowledge the message within the 201 timeout period. This 202 policy should be selected only if your replication 203 group is small, and its various environments 204 are on extremely reliable networks and servers. 205 </p> 206 </li> 207 <li> 208 <p> 209 <code class="literal">DB_REPMGR_ACKS_QUORUM</code> 210 211 </p> 212 <p> 213 A quorum of electable peers must acknowledge the message within the timeout period. 214 A quorum is reached when acknowledgments are received from the minimum number 215 of environments needed to ensure that the record remains durable 216 if an election is held. That is, the master wants to hear from enough 217 electable replicas that they have committed the record so that if an election 218 is held, the master knows the record will exist even if a new master is selected. 219 </p> 220 </li> 221 </ul> 222 </div> 223 <p> 224 By default, a quorum of electable peers must must acknowledge a permanent 225 message in order for it considered to have been successfully 226 transmitted. The actual number of replicas that must respond is 227 calculated using the value set with 228 <span><code class="methodname">DB_ENV->rep_set_nsites()</code>.</span> 229 230 231</p> 232 </div> 233 <div class="sect2" lang="en" xml:lang="en"> 234 <div class="titlepage"> 235 <div> 236 <div> 237 <h3 class="title"><a id="fmwrkpermtimeout"></a>Setting the Permanent Message Timeout</h3> 238 </div> 239 </div> 240 </div> 241 <p> 242 The permanent message timeout represents the 243 maximum amount of time the committing thread 244 will block waiting for message 245 acknowledgments. If sufficient 246 acknowledgments arrive before this timeout has 247 expired, the thread continues operations as 248 normal. However, if this timeout expires, the 249 committing thread flushes its transaction log 250 buffer before continuing with normal 251 operations. 252 </p> 253 <p> 254 You set the timeout value using the 255 <code class="methodname">DB_ENV->rep_set_timeout()</code> 256 257 method. When you do this, you provide the 258 <code class="literal">DB_REP_ACK_TIMEOUT</code> value to 259 the <code class="literal">which</code> parameter, and the 260 timeout value in microseconds to the 261 <code class="literal">timeout</code> parameter. 262 </p> 263 <p> 264 For example: 265 </p> 266 <pre class="programlisting"> dbenv->rep_set_timeout(dbenv, DB_REP_ACK_TIMEOUT, 100); </pre> 267 <p> 268 This timeout value can be set at anytime during the 269 life of the application. 270 </p> 271 </div> 272 <div class="sect2" lang="en" xml:lang="en"> 273 <div class="titlepage"> 274 <div> 275 <div> 276 <h3 class="title"><a id="perm2fmwrkexample"></a>Adding a Permanent Message Policy to 277 <span>ex_rep_gsg_repmgr</span> 278 279 280 </h3> 281 </div> 282 </div> 283 </div> 284 <p> 285 For illustration purposes, we will now update 286 <code class="literal">ex_rep_gsg_repmgr</code> 287 288 289 such that it requires only one acknowledgment from 290 a replica on transactional commits. Also, we will give 291 this acknowledgment a 500 microsecond timeout 292 value. This means that our application's main 293 thread will block for up to 500 microseconds waiting 294 for an acknowledgment. If it does not receive at 295 least one acknowledgment in that amount of time, 296 DB will flush the transaction logs to disk 297 before continuing on. 298 </p> 299 <p> 300 This is a very simple update. We can perform the 301 entire thing immediately before we parse our 302 command line options. This is where we configure 303 our environment handle anyway, so it is a good 304 place to put it. 305 </p> 306 <pre class="programlisting"> if ((ret = create_env(progname, &dbenv)) != 0) 307 goto err; 308 309 /* Default priority is 100 */ 310 dbenv->rep_set_priority(dbenv, 100); 311 <strong class="userinput"><code>/* Permanent messages require at least one ack */ 312 dbenv->repmgr_set_ack_policy(dbenv, DB_REPMGR_ACKS_ONE); 313 /* Give 500 microseconds to receive the ack */ 314 dbenv->rep_set_timeout(dbenv, DB_REP_ACK_TIMEOUT, 500);</code></strong> 315 316 /* Collect the command line options */ 317 while ((ch = getopt(argc, argv, "h:<strong class="userinput"><code>l:n:p:r:</code></strong>")) != EOF) 318 319 ... </pre> 320 </div> 321 </div> 322 <div class="navfooter"> 323 <hr /> 324 <table width="100%" summary="Navigation footer"> 325 <tr> 326 <td width="40%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a>��</td> 327 <td width="20%" align="center"> 328 <a accesskey="u" href="repapp.html">Up</a> 329 </td> 330 <td width="40%" align="right">��<a accesskey="n" href="electiontimes.html">Next</a></td> 331 </tr> 332 <tr> 333 <td width="40%" align="left" valign="top">Adding the Replication Manager to 334 <span>ex_rep_gsg_simple</span> 335 336 337 ��</td> 338 <td width="20%" align="center"> 339 <a accesskey="h" href="index.html">Home</a> 340 </td> 341 <td width="40%" align="right" valign="top">��Managing Election Times</td> 342 </tr> 343 </table> 344 </div> 345 </body> 346</html> 347