Module evel

Description
Data Types
Function Index
Function Details

An Eventual Leader Election Library.

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

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.

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