125 lines
6.7 KiB
HTML
125 lines
6.7 KiB
HTML
<!--$Id: rep_elect.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
|
<!--See the file LICENSE for redistribution information.-->
|
|
<html>
|
|
<head>
|
|
<title>Berkeley DB: DB_ENV->rep_elect</title>
|
|
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
|
|
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<table width="100%"><tr valign=top>
|
|
<td>
|
|
<b>DB_ENV->rep_elect</b>
|
|
</td>
|
|
<td align=right>
|
|
<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a>
|
|
<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td>
|
|
</tr></table>
|
|
<hr size=1 noshade>
|
|
<tt>
|
|
<b><pre>
|
|
#include <db.h>
|
|
<p>
|
|
int
|
|
DB_ENV->rep_elect(DB_ENV *env,
|
|
u_int32_t nsites, u_int32_t nvotes, u_int32_t flags);
|
|
</pre></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: DB_ENV->rep_elect</b>
|
|
<p>The DB_ENV->rep_elect method holds an election for the master of a replication
|
|
group.</p>
|
|
<p>The DB_ENV->rep_elect method is not called by most replication
|
|
applications. It should only be called by applications implementing
|
|
their own network transport layer, explicitly holding replication group
|
|
elections and handling replication messages outside of the replication
|
|
manager framework.</p>
|
|
<p>If the election is successful, Berkeley DB will notify the application of
|
|
the results of the election by means of either the
|
|
<a href="../api_c/env_event_notify.html#DB_EVENT_REP_ELECTED">DB_EVENT_REP_ELECTED</a> or <a href="../api_c/env_event_notify.html#DB_EVENT_REP_NEWMASTER">DB_EVENT_REP_NEWMASTER</a> events
|
|
(see <a href="../api_c/env_event_notify.html">DB_ENV->set_event_notify</a> method for more information). The
|
|
application is responsible for adjusting its relationship to the other
|
|
database environments in the replication group, including directing
|
|
all database updates to the newly selected master, in accordance with
|
|
the results of the election.</p>
|
|
<p>The thread of control that calls the DB_ENV->rep_elect method must not be the
|
|
thread of control that processes incoming messages; processing the
|
|
incoming messages is necessary to successfully complete an election.</p>
|
|
<b>Parameters</b> <br>
|
|
<b>nsites</b><ul compact><li>The <b>nsites</b> parameter specifies the number of replication sites
|
|
expected to participate in the election. Once the current site has
|
|
election information from that many sites, it will short-circuit the
|
|
election and immediately cast its vote for a new master. The
|
|
<b>nsites</b> parameter must be no less than
|
|
<b>nvotes</b>, or 0 if the election should use the value previously set
|
|
using the <a href="../api_c/rep_nsites.html">DB_ENV->rep_set_nsites</a> method. If an application is using master
|
|
leases, then the value <b>must</b> be 0 and the value from
|
|
<a href="../api_c/rep_nsites.html">DB_ENV->rep_set_nsites</a> method must be used.</ul>
|
|
<b>nvotes</b><ul compact><li>The <b>nvotes</b> parameter specifies the minimum number of replication
|
|
sites from which the current site must have election information, before
|
|
the current site will cast a vote for a new master. The <b>nvotes</b>
|
|
parameter must be no greater than <b>nsites</b>,
|
|
or 0 if the election should use the value ((<b>nsites</b> / 2) + 1) as
|
|
the <b>nvotes</b> argument.</ul>
|
|
<b>flags</b><ul compact><li>The <b>flags</b> parameter is currently unused, and must be set to 0.</ul>
|
|
<br>
|
|
<p>Elections are done in two parts: first, replication sites collect
|
|
information from the other replication sites they know about, and
|
|
second, replication sites cast their votes for a new master. The second
|
|
phase is triggered by one of two things: either the replication site
|
|
gets election information from <b>nsites</b> sites, or the election
|
|
<b>timeout</b> expires. Once the second phase is triggered, the
|
|
replication site will cast a vote for the new master of its choice if,
|
|
and only if, the site has election information from at least
|
|
<b>nvotes</b> sites. If a site receives <b>nvotes</b> votes for it
|
|
to become the new master, then it will become the new master.</p>
|
|
<p>We recommend <b>nvotes</b> be set to at least:</p>
|
|
<blockquote><pre>(sites participating in the election / 2) + 1</pre></blockquote>
|
|
<p>to ensure there are never more than two masters active at the same time
|
|
even in the case of a network partition. When a network partitions, the
|
|
side of the partition with more than half the environments will elect a
|
|
new master and continue, while the environments communicating with fewer
|
|
than half of the environments will fail to find a new master, as no site
|
|
can get <b>nvotes</b> votes.</p>
|
|
<p>We recommend <b>nsites</b> be set to:</p>
|
|
<blockquote><pre>number of sites in the replication group - 1</pre></blockquote>
|
|
<p>when choosing a new master after a current master fails. This allows
|
|
the group to reach a consensus without having to wait for the timeout
|
|
to expire.</p>
|
|
<p>When choosing a master from among a group of client
|
|
sites all restarting at the same time, it makes more sense to set
|
|
<b>nsites</b> to the total number of sites in the group, since there is no
|
|
known missing site. Furthermore, in order to ensure the best choice
|
|
from among sites that may take longer to boot than the local site,
|
|
setting <b>nvotes</b> also to this same total number of sites will
|
|
guarantee that every site in the group is considered. Alternatively,
|
|
using the special timeout for full elections allows full participation
|
|
on restart but allows election of a master if one site does not
|
|
reboot and rejoin the group in a reasonable amount of time. (See the
|
|
<a href="../ref/rep/elect.html">Elections</a>
|
|
section in the Berkeley DB Reference Guide for more information.)</p>
|
|
<p>Setting <b>nsites</b> to lower values can increase the speed of an
|
|
election, but can also result in election failure, and is usually not
|
|
recommended.</p>
|
|
<a name="2"><!--meow--></a>
|
|
<br><b>Errors</b>
|
|
<p>The DB_ENV->rep_elect method
|
|
may fail and return one of the following non-zero errors:</p>
|
|
<br>
|
|
<b>DB_REP_UNAVAIL</b><ul compact><li>The replication group was unable to elect a master, or was unable to
|
|
complete the election in the election timeout period (see
|
|
<a href="../api_c/rep_timeout.html">DB_ENV->rep_set_timeout</a> method for more information).</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<br><b>Class</b>
|
|
<a href="../api_c/env_class.html">DB_ENV</a>
|
|
<br><b>See Also</b>
|
|
<a href="../api_c/rep_list.html">Replication and Related Methods</a>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a>
|
|
</td></tr></table>
|
|
<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
|
</body>
|
|
</html>
|