1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
<!--$Id: rep_elect.so,v 1.22 2005/06/10 14:50:18 bostic Exp $-->
<!--Copyright 1997-2005 by Sleepycat Software, Inc.-->
<!--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>
<h3>DB_ENV->rep_elect</h3>
</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>
<h3><pre>
#include <db.h>
<p>
int
DB_ENV->rep_elect(DB_ENV *env, int nsites, int nvotes,
int priority, u_int32_t timeout, int *envid, u_int32_t flags);
</pre></h3>
<hr size=1 noshade>
<h3>Description: DB_ENV->rep_elect</h3>
<p>The DB_ENV->rep_elect method holds an election for the master of a replication
group.</p>
<p>If the election is successful, the new master's ID may be the ID of the
previous master, or the ID of the current replication site. 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 this 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>
<h3>Parameters</h3>
<dl compact>
<dt><b>envid</b><dd>The <b>envid</b> parameter references memory into which
the newly elected master's ID is copied.
<dt><b>nsites</b><dd>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 a positive integer, no less than
<b>nvotes</b>.
<dt><b>nvotes</b><dd>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 a positive integer and 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.
<dt><b>priority</b><dd>The <b>priority</b> parameter is the priority of this environment. It
must be a positive integer, or 0 if this environment is not permitted
to become a master (see <a href="../ref/rep/pri.html">Replication
environment priorities</a> for more information).
<dt><b>timeout</b><dd>The <b>timeout</b> parameter specifies a timeout period for an election.
<dt><b>flags</b><dd>The <b>flags</b> parameter is currently unused, and must be set to 0.
</dl>
<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>sites participating in the election - 1</pre></blockquote>
<p>This allows replication groups to elect a new master immediately if the
current master fails. Setting the <b>nsites</b> value to the number
of sites participating in the replication election ensures all sites in
the group get the chance to participate in the election, at the cost of
potentially slower elections. 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>
<h3>Errors</h3>
<p>The DB_ENV->rep_elect method
may fail and return one of the following non-zero errors:</p>
<dl compact>
<dt>DB_REP_UNAVAIL<dd>The replication group was unable to elect a master, or was unable to
complete the election in the specified <b>timeout</b> period.
</dl>
<hr size=1 noshade>
<h3>Class</h3>
<a href="../api_c/env_class.html">DB_ENV</a>
<h3>See Also</h3>
<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><a href="../sleepycat/legal.html">Copyright (c) 1996-2005</a> <a href="http://www.sleepycat.com">Sleepycat Software, Inc.</a> - All rights reserved.</font>
</body>
</html>
|
