Module gen_leader

Leader election behavior.

Authors: Hans Svensson (hanssv@cs.chalmers.se), Thomas Arts (thomas.arts@ituniv.se), Ulf Wiger (ulf.wiger@ericsson.com).

Description

Leader election behavior.

This application implements a leader election behavior modeled after gen_server. This behavior intends to make it reasonably straightforward to implement a fully distributed server with master-slave semantics.

The gen_leader behavior supports nearly everything that gen_server does (some functions, such as multicall() and the internal timeout, have been removed), and adds a few callbacks and API functions to support leader election etc.

Also included is an example program, a global dictionary, based on the modules gen_leader and dict. The callback implementing the global dictionary is called 'test_cb', for no particularly logical reason.

New version: The internal leader election algorithm was faulty and has been replaced with a new version based on a different leader election algorithm. As a consequence of this the query functions alive and down can no longer be provided. The new algorithm also make use of an incarnation parameter, by default written to disk in the function incarnation. This implies that only one gen_leader per node is permitted, if used in a diskless environment, incarnation must be adapted.

Data Types

callerRef()

callerRef() = {pid(), reference()}

See gen_server.

election()

election() = tuple()

Opaque state of the gen_leader behaviour.

name()

name() = atom()

A locally registered name.

node()

node() = atom()

A node name.

serverRef()

serverRef() = Name | {name(), node()} | {global, Name} | pid()

See gen_server.

Function Index

call/2Equivalent to gen_server:call/2, but with a slightly different exit reason if something goes wrong.
call/3Equivalent to gen_server:call/3, but with a slightly different exit reason if something goes wrong.
candidates/1Returns a list of known candidates.
cast/2Equivalent to gen_server:cast / 2.
leader_call/2Makes a call (similar to gen_server:call/2) to the leader.
leader_call/3Makes a call (similar to gen_server:call/3) to the leader.
leader_cast/2Similar to gen_server:cast/2 but will be forwarded to the leader via the local gen_leader instance.
reply/2Equivalent to gen_server:reply / 2.
start/6Starts a gen_leader process without linking to the parent.
start_link/6Starts a gen_leader process.
workers/1Returns a list of known workers.

Function Details

call/2

call(Name::serverRef(), Request) -> term()

Equivalent to gen_server:call/2, but with a slightly different exit reason if something goes wrong. This function calls the gen_leader process exactly as if it were a gen_server (which, for practical purposes, it is.)

call/3

call(Name::serverRef(), Request, Timeout::integer()) -> Reply

Equivalent to gen_server:call/3, but with a slightly different exit reason if something goes wrong. This function calls the gen_leader process exactly as if it were a gen_server (which, for practical purposes, it is.)

candidates/1

candidates(E::election()) -> [node()]

Returns a list of known candidates.

cast/2

cast() -> term()

Equivalent to gen_server:cast / 2.

leader_call/2

leader_call(Name::name(), Request::term()) -> Reply

Makes a call (similar to gen_server:call/2) to the leader. The call is forwarded via the local gen_leader instance, if that one isn't actually the leader. The client will exit if the leader dies while the request is outstanding.

This function uses gen:call/3, and is subject to the same default timeout as e.g. gen_server:call/2.

leader_call/3

leader_call(Name::name(), Request::term(), Timeout::integer()) -> Reply

Makes a call (similar to gen_server:call/3) to the leader. The call is forwarded via the local gen_leader instance, if that one isn't actually the leader. The client will exit if the leader dies while the request is outstanding.

leader_cast/2

leader_cast(Name::name(), Msg::term()) -> ok

Similar to gen_server:cast/2 but will be forwarded to the leader via the local gen_leader instance.

reply/2

reply(From::callerRef(), Reply::term()) -> Void

Equivalent to gen_server:reply / 2.

start/6

start(Name::node(), CandidateNodes::[node()], Workers::[node()], Mod::atom(), Arg, Options::list()) -> {ok, pid()}

Starts a gen_leader process without linking to the parent.

start_link/6

start_link(Name::atom(), CandidateNodes::[atom()], Workers::[atom()], Mod::atom(), Arg, Options::list()) -> {ok, pid()}

Starts a gen_leader process.
NameThe locally registered name of the process
CandidateNodesThe names of nodes capable of assuming a leadership role
Workers The names of nodes that will be part of the "cluster", but cannot ever assume a leadership role.
ModThe name of the callback module
ArgArgument passed on to Mod:init/1
OptionsSame as gen_server's Options

The list of candidates needs to be known from the start. Workers can be added at runtime.

workers/1

workers(E::election()) -> [node()]

Returns a list of known workers.


Generated by EDoc, Dec 25 2007, 02:41:20.