Module evel

An Eventual Leader Election Library.

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.

Description

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).

Data Types

candidate()

candidate() = pid()

A candidate of an election.

certificate()

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()

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.

async: - If the value is true, the dismissal is processed by an asynchronous manner. - The default value is false.

elect_option()

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).

link: - If the value is true, the candidate process and the certificate process will be linked. - The default value is true.

election_id()

election_id() = term()

The identifier of an election. In each election, only one leader is elected.

find_option()

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.

voter_count: - The number of voters which vote for the election. - The larger value is more tolerant to node failures and cluster member changes but more overhead occurs. - Usually, but it is not mandatory, the same value in both elect/2 and find_leader/2 will be specified in the same election. - The default value is 5.

leader()

leader() = {winner(), certificate()}

A candidate which wins the electoin and is certified as the leader.

winner()

winner() = candidate()

The winner of an election.

Function Index

dismiss/1Equivalent to dismiss(Leader, []).
dismiss/2Dismisses the leader.
elect/2Equivalent to elect(ElectionId, Candidate, []).
elect/3Elects the leader in the election.
find_leader/1Equivalent to find_leader(ElectionId, []).
find_leader/2Finds the leader elected in the election.
get_certificate/1Gets the certificate part of Leader
get_winner/1Gets the winner part of Leader
is_leader/1Returns true if X is a leader(), otherwise false
known_leaders/0Returns a list of locally known leaders.

Function Details

dismiss/1

dismiss(Leader::leader()) -> ok

Equivalent to dismiss(Leader, []).

dismiss/2

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/2

elect(ElectionId::election_id(), Candidate::candidate()) -> leader()

Equivalent to elect(ElectionId, Candidate, []).

elect/3

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/1

find_leader(ElectionId::election_id()) -> {ok, leader()} | error

Equivalent to find_leader(ElectionId, []).

find_leader/2

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/1

get_certificate(Leader::leader()) -> certificate()

Gets the certificate part of Leader

get_winner/1

get_winner(Leader::leader()) -> winner()

Gets the winner part of Leader

is_leader/1

is_leader(X::leader() | term()) -> boolean()

Returns true if X is a leader(), otherwise false

known_leaders/0

known_leaders() -> [{election_id(), leader()}]

Returns a list of locally known leaders


Generated by EDoc, Oct 29 2017, 01:52:16.