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