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>DbEnv::rep_elect()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" /> 10 <link rel="up" href="rep.html" title="Chapter 11. Replication Methods" /> 11 <link rel="prev" href="rep.html" title="Chapter 11. Replication Methods" /> 12 <link rel="next" href="repget_clockskew.html" title="DbEnv::rep_get_clockskew()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbEnv::rep_elect()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="rep.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 11. 23 Replication Methods 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="repget_clockskew.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="repelect"></a>DbEnv::rep_elect()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbEnv::rep_elect(u_int32_t nsites, u_int32_t nvotes, u_int32_t flags);</pre> 42 <p> 43 The <code class="methodname">DbEnv::rep_elect()</code> method holds an election for the master of a 44 replication group. 45 </p> 46 <p> 47 The <code class="methodname">DbEnv::rep_elect()</code> method is not called by most replication 48 applications. It should only be called by Base API applications implementing 49 their own network transport layer, explicitly holding replication 50 group elections and handling replication messages outside of the 51 Replication Manager framework. 52 </p> 53 <p> 54 If the election is successful, Berkeley DB will notify the application 55 of the results of the election by means of either the 56 <a class="link" href="envevent_notify.html#event_notify_DB_EVENT_REP_ELECTED">DB_EVENT_REP_ELECTED</a> 57 or <a class="link" href="envevent_notify.html#event_notify_DB_EVENT_REP_NEWMASTER">DB_EVENT_REP_NEWMASTER</a> 58 events (see <a class="xref" href="envevent_notify.html" title="DbEnv::set_event_notify()">DbEnv::set_event_notify()</a> 59 method for more information). The application is responsible for 60 adjusting its relationship to the other database environments in the 61 replication group, including directing all database updates to the 62 newly selected master, in accordance with the results of the election. 63 </p> 64 <p> 65 The thread of control that calls the <code class="methodname">DbEnv::rep_elect()</code> method must 66 not be the thread of control that processes incoming messages; 67 processing the incoming messages is necessary to successfully complete 68 an election. 69 </p> 70 <p> 71 Before calling this method, the enclosing database environment must 72 already have been opened by calling the 73 <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> method and must 74 already have been configured to send replication messages by 75 calling the <a class="xref" href="reptransport.html" title="DbEnv::rep_set_transport()">DbEnv::rep_set_transport()</a> 76 method. 77 </p> 78 <div class="sect2" lang="en" xml:lang="en"> 79 <div class="titlepage"> 80 <div> 81 <div> 82 <h3 class="title"><a id="id1700576"></a>How Elections are Held</h3> 83 </div> 84 </div> 85 </div> 86 <p> 87 Elections are done in two parts: first, replication sites collect information from the other replication 88 sites they know about, and second, replication sites cast their votes for a new master. The second phase 89 is triggered by one of two things: either the replication site gets election information from <span class="bold"><strong>nsites</strong></span> sites, or the election timeout 90 expires. Once the second phase is triggered, the replication site will cast a vote for the new master of 91 its choice if, and only if, the site has election information from at least <span class="bold"><strong>nvotes</strong></span> sites. If a site receives <span class="bold"><strong>nvotes</strong></span> 92 votes for it to become the new master, then it will become the new master. 93 </p> 94 <p> 95 We recommend <span class="bold"><strong>nvotes</strong></span> be set to at least: 96 </p> 97 <pre class="programlisting"> (sites participating in the election / 2) + 1</pre> 98 <p> 99 to ensure there are never more than two masters active at the same time even in the case of a 100 network partition. When a network partitions, the side of the partition with more than half the 101 environments will elect a new master and continue, while the environments communicating with fewer 102 than half of the environments will fail to find a new master, as no site can get 103 <span class="bold"><strong>nvotes</strong></span> votes. 104 </p> 105 <p> 106 We recommend <span class="bold"><strong>nsites</strong></span> be set to: 107 </p> 108 <pre class="programlisting"> number of sites in the replication group - 1</pre> 109 <p> 110 when choosing a new master after a current master fails. This allows the group to reach a consensus 111 without having to wait for the timeout to expire. 112 </p> 113 <p> 114 When choosing a master from among a group of client sites all restarting at the same time, it makes 115 more sense to set <span class="bold"><strong>nsites</strong></span> to the total number of sites in the group, 116 since there is no known missing site. Furthermore, in order to ensure the best choice from among 117 sites that may take longer to boot than the local site, setting <span class="bold"><strong>nvotes</strong></span> also to this same total number of sites will guarantee that 118 every site in the group is considered. Alternatively, using the special timeout for full elections 119 allows full participation on restart but allows election of a master if one site does not reboot and 120 rejoin the group in a reasonable amount of time. (See the <a href="../../programmer_reference/rep_elect.html" class="olink">Elections</a> section in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em> for more information.) 121 </p> 122 <p> 123 Setting <span class="bold"><strong>nsites</strong></span> to lower values can increase the speed of an 124 election, but can also result in election failure, and is usually not recommended. 125 </p> 126 </div> 127 <div class="sect2" lang="en" xml:lang="en"> 128 <div class="titlepage"> 129 <div> 130 <div> 131 <h3 class="title"><a id="id1700760"></a>Parameters</h3> 132 </div> 133 </div> 134 </div> 135 <div class="sect3" lang="en" xml:lang="en"> 136 <div class="titlepage"> 137 <div> 138 <div> 139 <h4 class="title"><a id="id1700729"></a>flags</h4> 140 </div> 141 </div> 142 </div> 143 <p> 144 The <span class="bold"><strong>flags</strong></span> parameter is currently 145 unused, and must be set to 0. 146 </p> 147 </div> 148 <div class="sect3" lang="en" xml:lang="en"> 149 <div class="titlepage"> 150 <div> 151 <div> 152 <h4 class="title"><a id="id1700738"></a>nsites</h4> 153 </div> 154 </div> 155 </div> 156 <p> 157 The <span class="bold"><strong>nsites</strong></span> parameter specifies the 158 number of replication sites expected to participate in the election. 159 Once the current site has election information from that many sites, 160 it will short-circuit the election and immediately cast its vote for a 161 new master. The <span class="bold"><strong>nsites</strong></span> parameter must 162 be no less than <span class="bold"><strong>nvotes</strong></span>, or 0 if the 163 election should use the value previously set using the 164 <a class="xref" href="repnsites.html" title="DbEnv::rep_set_nsites()">DbEnv::rep_set_nsites()</a> 165 method. If an application is using master leases, then the value 166 <span class="bold"><strong>must</strong></span> be 0 and the value from 167 <a class="xref" href="repnsites.html" title="DbEnv::rep_set_nsites()">DbEnv::rep_set_nsites()</a> 168 method must be used. 169 </p> 170 </div> 171 <div class="sect3" lang="en" xml:lang="en"> 172 <div class="titlepage"> 173 <div> 174 <div> 175 <h4 class="title"><a id="id1700739"></a>nvotes</h4> 176 </div> 177 </div> 178 </div> 179 <p> 180 The <span class="bold"><strong>nvotes</strong></span> parameter specifies the 181 minimum number of replication sites from which the current site must 182 have election information, before the current site will cast a vote 183 for a new master. The <span class="bold"><strong>nvotes</strong></span> 184 parameter must be no greater than <span class="bold"><strong>nsites</strong></span>, or 0 if the election should use the 185 value ((<span class="bold"><strong>nsites</strong></span> / 2) + 1) as the 186 <span class="bold"><strong>nvotes</strong></span> argument. 187 </p> 188 </div> 189 </div> 190 <div class="sect2" lang="en" xml:lang="en"> 191 <div class="titlepage"> 192 <div> 193 <div> 194 <h3 class="title"><a id="id1700935"></a>Errors</h3> 195 </div> 196 </div> 197 </div> 198 <p> 199 The <code class="methodname">DbEnv::rep_elect()</code> <span> 200 201 <span> 202 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 203 exception, encapsulating one of the following non-zero errors, or return one 204 of the following non-zero errors: 205 </span> 206 </span> 207 </p> 208 <div class="sect3" lang="en" xml:lang="en"> 209 <div class="titlepage"> 210 <div> 211 <div> 212 <h4 class="title"><a id="id1700645"></a>DB_REP_UNAVAIL</h4> 213 </div> 214 </div> 215 </div> 216 <p> 217 The replication group was unable to elect a master, or was unable to 218 complete the election in the election timeout period (see 219 <a class="xref" href="repset_timeout.html" title="DbEnv::rep_set_timeout()">DbEnv::rep_set_timeout()</a> 220 method for more information). 221 </p> 222 </div> 223 <div class="sect3" lang="en" xml:lang="en"> 224 <div class="titlepage"> 225 <div> 226 <div> 227 <h4 class="title"><a id="id1701030"></a>EINVAL</h4> 228 </div> 229 </div> 230 </div> 231 <p> 232 If the database environment was not already configured to 233 communicate with a replication group by a call to 234 <a class="xref" href="reptransport.html" title="DbEnv::rep_set_transport()">DbEnv::rep_set_transport()</a>; 235 if the database environment was not already opened; 236 if this method is called from a Replication Manager 237 application; or if an invalid flag value or parameter 238 was specified. 239 </p> 240 </div> 241 </div> 242 <div class="sect2" lang="en" xml:lang="en"> 243 <div class="titlepage"> 244 <div> 245 <div> 246 <h3 class="title"><a id="id1700646"></a>Class</h3> 247 </div> 248 </div> 249 </div> 250 <p> 251 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> 252 </p> 253 </div> 254 <div class="sect2" lang="en" xml:lang="en"> 255 <div class="titlepage"> 256 <div> 257 <div> 258 <h3 class="title"><a id="id1700782"></a>See Also</h3> 259 </div> 260 </div> 261 </div> 262 <p> 263 <a class="xref" href="rep.html#replist" title="Replication and Related Methods">Replication and Related Methods</a> 264 </p> 265 </div> 266 </div> 267 <div class="navfooter"> 268 <hr /> 269 <table width="100%" summary="Navigation footer"> 270 <tr> 271 <td width="40%" align="left"><a accesskey="p" href="rep.html">Prev</a> </td> 272 <td width="20%" align="center"> 273 <a accesskey="u" href="rep.html">Up</a> 274 </td> 275 <td width="40%" align="right"> <a accesskey="n" href="repget_clockskew.html">Next</a></td> 276 </tr> 277 <tr> 278 <td width="40%" align="left" valign="top">Chapter 11. 279 Replication Methods 280 </td> 281 <td width="20%" align="center"> 282 <a accesskey="h" href="index.html">Home</a> 283 </td> 284 <td width="40%" align="right" valign="top"> DbEnv::rep_get_clockskew()</td> 285 </tr> 286 </table> 287 </div> 288 </body> 289</html> 290