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