docs/gsg_db_rep/CXX/elections.html

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