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