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