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>Holding Elections</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="introduction.html" title="Chapter 1. Introduction" /> 11 <link rel="previous" href="apioverview.html" title="The Replication APIs" /> 12 <link rel="next" href="permmessages.html" title="Permanent Message Handling" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Holding Elections</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="apioverview.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 1. Introduction</th> 23 <td width="20%" align="right"> <a accesskey="n" href="permmessages.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="elections"></a>Holding Elections</h2> 33 </div> 34 </div> 35 <div></div> 36 </div> 37 <p> 38 Finding a master environment is one of the fundamental activities that 39 every replication replica must perform. Upon startup, the 40 underlying DB replication code will attempt to 41 locate a master. If a master cannot be found, then the 42 environment should initiate an election. 43 </p> 44 <p> 45 How elections are held depends upon the API that you use to 46 implement replication. For example, if you are using the 47 replication framework elections are held transparently without any 48 input from your application's code. In this case, 49 DB will determine which environment is the master and which 50 are replicas. 51 </p> 52 <div class="sect2" lang="en" xml:lang="en"> 53 <div class="titlepage"> 54 <div> 55 <div> 56 <h3 class="title"><a id="influencingelections"></a>Influencing Elections</h3> 57 </div> 58 </div> 59 <div></div> 60 </div> 61 <p> 62 If you want to control the election process, you can declare 63 a specific environment to be the master. Note that for the replication framework, 64 it is only possible to do this at application startup. 65 Should the master become unavailable during run-time for any 66 reason, an election is held. The environment that receives 67 the most number of votes, wins the election and becomes the 68 master. A machine receives a vote because it has the most 69 number of log records. 70 </p> 71 <p> 72 Because ties are possible when elections are held, 73 it is possible to influence which environment will win 74 the election. How you do this depends on which API you 75 are using. In particular, if you are writing a custom replication 76 layer, then there are a great many ways to manually influence 77 elections. 78 </p> 79 <p> 80 One such mechanism is priorities. When votes are 81 cast during an election, both the number of log records 82 contained in the environment <span class="emphasis"><em>and</em></span> 83 the environment's priority are considered. So given two 84 environments with the same number of log records, votes 85 are cast for the environment with the higher priority. 86 </p> 87 <p> 88 Therefore, if you have a machine that you prefer to 89 become a master in the event of an election, assign it 90 a high priority. Assuming that the election is held at 91 a time when the preferred machine has up-to-date log 92 records, that machine will win the election. 93 </p> 94 </div> 95 <div class="sect2" lang="en" xml:lang="en"> 96 <div class="titlepage"> 97 <div> 98 <div> 99 <h3 class="title"><a id="winningelections"></a>Winning Elections</h3> 100 </div> 101 </div> 102 <div></div> 103 </div> 104 <p> 105 To win an election: 106 </p> 107 <div class="orderedlist"> 108 <ol type="1"> 109 <li> 110 <p> 111 There cannot currently be a 112 master environment. 113 </p> 114 </li> 115 <li> 116 <p> 117 The environment must have the most 118 recent log records. Part of 119 holding the election is 120 determining which environments have 121 the most recent log records. 122 This process happens 123 automatically; your code does 124 not need to involve itself in 125 this process. 126 </p> 127 </li> 128 <li> 129 <p> 130 The environment must receive the most 131 number of votes from the 132 replication environments that are 133 participating in the election. 134 </p> 135 </li> 136 </ol> 137 </div> 138 <p> 139 If you are using the replication framework, then in the event of a 140 tie vote the environment with the highest priority wins 141 the election. If two or more environments receive the same 142 number of votes and have the same priority, then 143 the underlying replication code picks one of the 144 environments to 145 be the winner. Which winner will be picked by the 146 replication code is unpredictable from the 147 perspective of your application code. 148 </p> 149 </div> 150 <div class="sect2" lang="en" xml:lang="en"> 151 <div class="titlepage"> 152 <div> 153 <div> 154 <h3 class="title"><a id="switchingmasters"></a>Switching Masters</h3> 155 </div> 156 </div> 157 <div></div> 158 </div> 159 <p> 160 To switch masters: 161 </p> 162 <div class="orderedlist"> 163 <ol type="1"> 164 <li> 165 <p> 166 Start up the environment that you want 167 to be master as normal. At this 168 time it is a replica. Make 169 sure this environment has a higher 170 priority than all the other 171 environments. 172 </p> 173 </li> 174 <li> 175 <p> 176 Allow the new environment to run for a 177 time as a replica. This allows 178 it to obtain the most recent 179 copies of the log files. 180 </p> 181 </li> 182 <li> 183 <p> 184 Shut down the current master. 185 This should force an election. 186 Because the new environment has the 187 highest priority, it will win 188 the election, provided it has 189 had enough time to obtain all 190 the log records. 191 </p> 192 </li> 193 <li> 194 <p> 195 Optionally restart the old 196 master environment. Because there is 197 currently a master environment, an 198 election will not be held and 199 the old master will now run as 200 a replica environment. 201 </p> 202 </li> 203 </ol> 204 </div> 205 </div> 206 </div> 207 <div class="navfooter"> 208 <hr /> 209 <table width="100%" summary="Navigation footer"> 210 <tr> 211 <td width="40%" align="left"><a accesskey="p" href="apioverview.html">Prev</a> </td> 212 <td width="20%" align="center"> 213 <a accesskey="u" href="introduction.html">Up</a> 214 </td> 215 <td width="40%" align="right"> <a accesskey="n" href="permmessages.html">Next</a></td> 216 </tr> 217 <tr> 218 <td width="40%" align="left" valign="top">The Replication APIs </td> 219 <td width="20%" align="center"> 220 <a accesskey="h" href="index.html">Home</a> 221 </td> 222 <td width="40%" align="right" valign="top"> Permanent Message Handling</td> 223 </tr> 224 </table> 225 </div> 226 </body> 227</html> 228