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 RepMgr" /> 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 52 <span>RepMgrGSG</span> 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 110 111 112 113 Note that you can set permanent message 114 policies at any time during the life of the 115 application. 116 </p> 117 <p> 118 The following permanent message policies are available when you use 119 the Replication Manager: 120</p> 121 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 122 <h3 class="title">Note</h3> 123 <p> 124 The following list mentions <span class="emphasis"><em>electable peer</em></span> 125 several times. This is simply another environment that can be 126 elected to be a master (that is, it has a priority greater than 0). 127 Do not confuse this with the concept of a peer as used for client 128 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 129 to client transfers. 130 </p> 131 </div> 132 <div class="itemizedlist"> 133 <ul type="disc"> 134 <li> 135 <p> 136 <code class="literal">DB_REPMGR_ACKS_NONE</code> 137 138 </p> 139 <p> 140 No permanent message acknowledgments are required. If 141 this policy is selected, permanent message handling is 142 essentially "turned off." That is, the master will 143 never wait for replica acknowledgments. In this case, 144 transaction log data is either flushed or not strictly 145 depending on the type of commit that is being performed 146 (synchronous or asynchronous). 147 </p> 148 </li> 149 <li> 150 <p> 151 <code class="literal">DB_REPMGR_ACKS_ONE</code> 152 153 </p> 154 <p> 155 At least one replica must acknowledge the permanent 156 message within the timeout period. 157 </p> 158 </li> 159 <li> 160 <p> 161 <code class="literal">DB_REPMGR_ACKS_ONE_PEER</code> 162 163 </p> 164 <p> 165 At least one electable peer must acknowledge the permanent 166 message within the timeout period. 167 </p> 168 </li> 169 <li> 170 <p> 171 <code class="literal">DB_REPMGR_ACKS_ALL</code> 172 173 </p> 174 <p> 175 All replicas must acknowledge the message within 176 the timeout period. This 177 policy should be selected only if your replication 178 group has a small number of replicas, and those replicas 179 are on extremely reliable networks and servers. 180 </p> 181 <p> 182 When this flag is used, the actual number of 183 replicas that must respond is 184 determined by the value set for 185 186 <span><code class="methodname">DbEnv::rep_set_nsites()</code>.</span> 187 188 </p> 189 </li> 190 <li> 191 <p> 192 <code class="literal">DB_REPMGR_ACKS_ALL_PEERS</code> 193 194 </p> 195 <p> 196 All electable peers must acknowledge the message within the 197 timeout period. This 198 policy should be selected only if your replication 199 group is small, and its various environments 200 are on extremely reliable networks and servers. 201 </p> 202 </li> 203 <li> 204 <p> 205 <code class="literal">DB_REPMGR_ACKS_QUORUM</code> 206 207 </p> 208 <p> 209 A quorum of electable peers must acknowledge the message within the timeout period. 210 A quorum is reached when acknowledgments are received from the minimum number 211 of environments needed to ensure that the record remains durable 212 if an election is held. That is, the master wants to hear from enough 213 electable replicas that they have committed the record so that if an election 214 is held, the master knows the record will exist even if a new master is selected. 215 </p> 216 </li> 217 </ul> 218 </div> 219 <p> 220 By default, a quorum of electable peers must must acknowledge a permanent 221 message in order for it considered to have been successfully 222 transmitted. The actual number of replicas that must respond is 223 calculated using the value set with 224 225 <span><code class="methodname">DbEnv::rep_set_nsites()</code>.</span> 226 227</p> 228 </div> 229 <div class="sect2" lang="en" xml:lang="en"> 230 <div class="titlepage"> 231 <div> 232 <div> 233 <h3 class="title"><a id="fmwrkpermtimeout"></a>Setting the Permanent Message Timeout</h3> 234 </div> 235 </div> 236 </div> 237 <p> 238 The permanent message timeout represents the 239 maximum amount of time the committing thread 240 will block waiting for message 241 acknowledgments. If sufficient 242 acknowledgments arrive before this timeout has 243 expired, the thread continues operations as 244 normal. However, if this timeout expires, the 245 committing thread flushes its transaction log 246 buffer before continuing with normal 247 operations. 248 </p> 249 <p> 250 You set the timeout value using the 251 252 <code class="methodname">DbEnv::rep_set_timeout()</code> 253 method. When you do this, you provide the 254 <code class="literal">DB_REP_ACK_TIMEOUT</code> value to 255 the <code class="literal">which</code> parameter, and the 256 timeout value in microseconds to the 257 <code class="literal">timeout</code> parameter. 258 </p> 259 <p> 260 For example: 261 </p> 262 <pre class="programlisting"> dbenv->rep_set_timeout(DB_REP_ACK_TIMEOUT, 100); </pre> 263 <p> 264 This timeout value can be set at anytime during the 265 life of the application. 266 </p> 267 </div> 268 <div class="sect2" lang="en" xml:lang="en"> 269 <div class="titlepage"> 270 <div> 271 <div> 272 <h3 class="title"><a id="perm2fmwrkexample"></a>Adding a Permanent Message Policy to 273 274 <span>RepMgrGSG</span> 275 276 </h3> 277 </div> 278 </div> 279 </div> 280 <p> 281 For illustration purposes, we will now update 282 283 <code class="literal">RepMgrGSG</code> 284 285 such that it requires only one acknowledgment from 286 a replica on transactional commits. Also, we will give 287 this acknowledgment a 500 microsecond timeout 288 value. This means that our application's main 289 thread will block for up to 500 microseconds waiting 290 for an acknowledgment. If it does not receive at 291 least one acknowledgment in that amount of time, 292 DB will flush the transaction logs to disk 293 before continuing on. 294 </p> 295 <p> 296 This is a very simple update. We can perform the 297 entire thing in 298 <code class="methodname">RepMgrGSG::init()</code> 299 300 immediately after we set the application's priority 301 and before we open our environment handle. 302 </p> 303 <pre class="programlisting">int RepMgrGSG::init(RepConfigInfo *config) 304{ 305 int ret = 0; 306 307 app_config = config; 308 309 dbenv.set_errfile(stderr); 310 dbenv.set_errpfx(progname); 311 312 if ((ret = dbenv.repmgr_set_local_site(app_config->this_host.host, 313 app_config->this_host.port, 0, 0)) != 0) { 314 cerr << "Could not set listen address to host:port " 315 << app_config->this_host.host << ":" 316 << app_config->this_host.port 317 << "error: " << ret << endl; 318 } 319 320 for ( REP_HOST_INFO *cur = app_config->other_hosts; cur != NULL; 321 cur = cur->next) { 322 if ((ret = dbenv.repmgr_add_remote_site(cur->host, cur->port, 323 NULL, 0)) != 0) { 324 cerr << "could not add site." << endl 325 } 326 } 327 328 if (app_config->totalsites > 0) { 329 try { 330 if ((ret = dbenv.rep_set_nsites(app_config->totalsites)) != 0) 331 dbenv.err(ret, "set_nsites"); 332 } catch (DbException dbe) { 333 cerr << "rep_set_nsites call failed. Continuing." << endl; 334 } 335 } 336 337 dbenv.rep_set_priority(app_config->priority); 338 339 <strong class="userinput"><code>/* Permanent messages require at least one ack */ 340 dbenv.repmgr_set_ack_policy(DB_REPMGR_ACKS_ONE); 341 /* Give 500 microseconds to receive the ack */ 342 dbenv.rep_set_timeout(DB_REP_ACK_TIMEOUT, 500);</code></strong> 343 344 dbenv.set_cachesize(0, CACHESIZE, 0); 345 dbenv.set_flags(DB_TXN_NOSYNC, 1); 346 347 ... </pre> 348 </div> 349 </div> 350 <div class="navfooter"> 351 <hr /> 352 <table width="100%" summary="Navigation footer"> 353 <tr> 354 <td width="40%" align="left"><a accesskey="p" href="repmgr_init_example_c.html">Prev</a>��</td> 355 <td width="20%" align="center"> 356 <a accesskey="u" href="repapp.html">Up</a> 357 </td> 358 <td width="40%" align="right">��<a accesskey="n" href="electiontimes.html">Next</a></td> 359 </tr> 360 <tr> 361 <td width="40%" align="left" valign="top">Adding the Replication Manager to 362 363 <span>RepMgr</span> 364 365 ��</td> 366 <td width="20%" align="center"> 367 <a accesskey="h" href="index.html">Home</a> 368 </td> 369 <td width="40%" align="right" valign="top">��Managing Election Times</td> 370 </tr> 371 </table> 372 </div> 373 </body> 374</html> 375