Copyright © 2016 Takeru Ohta <phjgt308@gmail.com> This software is released under the MIT License. See the LICENSE file in the project root for full license information.
An Eventual Leader Election Library
This module provides functionality to elect the leader which will be eventually agreed by all member of the same distributed erlang cluster.
%% %% Elects the leader %% > Leader = evel:elect(foo, self()). %% %% Finds the leader of an election %% > {ok, Leader} = evel:find_leader(foo). > error = evel:find_leader(bar). %% %% Dismisses the leader %% > ok = evel:dismiss(foo). > error = evel:find_leader(foo).
candidate() = pid()
A candidate of an election.
certificate() = pid()
The certificate to gurantee the legitimacy of a leader.
If the certificate process is down, the corresponding candidate is no longer a leader.dismiss_option() = {unlink, boolean()} | {async, boolean()}
unlink:
- If there is one, it removes the link between the candidate and the corresponding certificate process.
- Thus, the candidate process can survive after the dismissal.
- The default value is false
.
true
, the dismissal is processed by an asynchronous manner.
- The default value is false
.
elect_option() = {priority, term()} | {link, boolean()} | find_option()
priority:
- The priority of the candidate.
- The smaller value means a higher priority.
- If conflict arises between multiple candidates in the same election, the highest priority one is eventually elected.
- The default value is erlang:system_time(micro_seconds)
.
true
, the candidate process and the certificate process will be linked.
- The default value is true
.
election_id() = term()
The identifier of an election. In each election, only one leader is elected.
find_option() = {timeout, timeout()} | {voter_count, pos_integer()}
timeout:
- If some voter do not respond in the period, their votes are ignored.
- The default value is 100
.
elect/2
and find_leader/2
will be specified in the same election.
- The default value is 5
.
leader() = {winner(), certificate()}
A candidate which wins the electoin and is certified as the leader.
winner() = candidate()
The winner of an election.
dismiss/1 | Equivalent to dismiss(Leader, []). |
dismiss/2 | Dismisses the leader. |
elect/2 | Equivalent to elect(ElectionId, Candidate, []). |
elect/3 | Elects the leader in the election. |
find_leader/1 | Equivalent to find_leader(ElectionId, []). |
find_leader/2 | Finds the leader elected in the election. |
get_certificate/1 | Gets the certificate part of Leader |
get_winner/1 | Gets the winner part of Leader |
is_leader/1 | Returns true if X is a leader() , otherwise false |
known_leaders/0 | Returns a list of locally known leaders. |
dismiss(Leader::leader()) -> ok
Equivalent to dismiss(Leader, []).
dismiss(Leader::leader(), Options::[dismiss_option()]) -> ok
Dismisses the leader
It kills (i.e.,exit(Pid, kill)
) the corresponding certificate process.
As a result, the candidate process may exit if it have linked to the certificate process.
elect(ElectionId::election_id(), Candidate::candidate()) -> leader()
Equivalent to elect(ElectionId, Candidate, []).
elect(ElectionId::election_id(), Candidate::candidate(), Options::[elect_option()]) -> Leader::leader()
Elects the leader in the election
If a leader have already been elected, it returns the leader.
If conflict arises between multiple candidates in the same election, the highest priority one is eventually elected (i.e., the leader is agreed by all member of the same erlang cluster).
Point to notice is that temporary coexist of multiple leaders is not prohibited. Some leaders will be eventually dismissed except highest priority one.
If you are interested in the expiration of the term of office (or the dismissal) of a leader, please you monitor the certificate process (i.e.,monitor(process, evel:get_certificate(Leader))
).
The down of the certificate process indicates the retirement of the leader.
find_leader(ElectionId::election_id()) -> {ok, leader()} | error
Equivalent to find_leader(ElectionId, []).
find_leader(ElectionId::election_id(), Options::[find_option()]) -> {ok, leader()} | error
Finds the leader elected in the election
If own node have already known the leader, this function will retrieve it from local ETS. Otherwise it will try fetching the election result from remote nodes.get_certificate(Leader::leader()) -> certificate()
Gets the certificate part of Leader
Gets the winner part of Leader
is_leader(X::leader() | term()) -> boolean()
Returns true
if X
is a leader()
, otherwise false
known_leaders() -> [{election_id(), leader()}]
Returns a list of locally known leaders
Generated by EDoc, Oct 29 2017, 01:52:16.