Behaviours: gen_leader.
Authors: Ulf Wiger (ulf.wiger@ericsson.com), Thomas Arts (thomas.arts@ituniv.se).
This particular callback module implements a global dictionary,
and is the back-end for the gdict
module.
broadcast() = term()
Whatever the leader decides to broadcast to the candidates.
commonReply() = {ok, state()} | {ok, broadcast(), state()} | {stop, reason(), state()}
Common set of valid replies from most callback functions.
dictionary() = tuple()
Same as from dict:new(); used in this module as State.
election() = tuple()
Opaque state of the gen_leader behaviour.
node() = atom()
A node name.
reason() = term()
Error information.
state() = dictionary()
Internal server state; In the general case, it can be any term.
code_change/4 | Similar to code_change/3 in a gen_server callback module, with the exception of the added argument E. |
elected/2 | Called by the leader it is elected leader, and each time a candidate recognizes the leader. |
from_leader/3 | Called by each candidate in response to a message from the leader. |
handle_DOWN/3 | Called by the leader when it detects loss of a candidate node. |
handle_call/3 | Equivalent to Mod:handle_call/3 in a gen_server. |
handle_cast/2 | Equivalent to Mod:handle_call/3 in a gen_server,
except (NOTE) for the possible return values. |
handle_info/2 | Equivalent to Mod:handle_info/3 in a gen_server,
except (NOTE) for the possible return values. |
handle_leader_call/4 | Called by the leader in response to a leader_call(). |
handle_leader_cast/3 | Called by the leader in response to a leader_cast(). |
init/1 | Equivalent to the init/1 function in a gen_server. |
surrendered/3 | Called by each candidate when it recognizes another instance as leader. |
terminate/2 | Equivalent to terminate/2 in a gen_server callback
module. |
code_change(FromVsn::string(), OldState::term(), E::election(), Extra::term()) -> {ok, NState} | {ok, NState, NElection}
Similar to code_change/3 in a gen_server callback module, with the exception of the added argument E.
Note that is also possible to update the otherwise opaque election() variable. This could be one way to add candidate nodes in service.
elected(State::state(), E::election()) -> {ok, Broadcast, NState}
Called by the leader it is elected leader, and each time a candidate recognizes the leader.
This function is only called in the leader instance, and
Broadcast
will be sent to all candidates
(when the leader is first elected), or to the new candidate that
has appeared.
Broadcast
might be the same as NState
,
but doesn't have to be. This is up to the application.
Example:
elected(Dict, E) -> {ok, Dict, Dict}.
from_leader(Msg::term(), State::state(), E::election()) -> {ok, NState}
Called by each candidate in response to a message from the leader.
In this particular module, the leader passes an update function to be applied to the candidate's state.
handle_DOWN(Node::node(), State::state(), E::election()) -> {ok, NState} | {ok, Broadcast, NState}
Called by the leader when it detects loss of a candidate node.
If the function returns a Broadcast
object, this will
be sent to all candidates, and they will receive it in the function
from_leader/3.
handle_call(Request::term(), From::callerRef(), State::state()) -> {reply, Reply, NState} | {noreply, state()} | {stop, Reason, Reply, NState} | commonReply()
Equivalent to Mod:handle_call/3
in a gen_server.
Note the difference in allowed return values. {ok,NState}
and {noreply,NState}
are synonymous.
{noreply,NState}
is allowed as a return value from
handle_call/3
, since it could arguably add some clarity,
but it has been disallowed from handle_cast/2
and
handle_info/2
handle_cast(Msg::term(), State::state()) -> commonReply()
Equivalent to Mod:handle_call/3
in a gen_server,
except (NOTE) for the possible return values.
handle_info(Msg::term(), State::state()) -> commonReply()
Equivalent to Mod:handle_info/3
in a gen_server,
except (NOTE) for the possible return values.
This function will be called in response to any incoming message not recognized as a call, cast, leader_call, leader_cast, from_leader message, internal leader negotiation message or system message.
handle_leader_call(Msg::term(), From::callerRef(), State::state(), E::election()) -> {reply, Reply, NState} | {reply, Reply, Broadcast, NState} | {noreply, state()} | {stop, Reason, Reply, NState} | commonReply()
Called by the leader in response to a leader_call().
If the return value includes a Broadcast
object, it will
be sent to all candidates, and they will receive it in the function
from_leader/3.
Example:
handle_leader_call({store,F}, From, Dict, E) -> NewDict = F(Dict), {reply, ok, {store, F}, NewDict}; handle_leader_call({leader_lookup,F}, From, Dict, E) -> Reply = F(Dict), {reply, Reply, Dict}.
In this particular example, leader_lookup
is not
actually supported from the gdict module, but would
be useful during complex operations, involving a series of updates
and lookups. Using leader_lookup
, all dictionary operations
are serialized through the leader; normally, lookups are served locally
and updates by the leader, which can lead to race conditions.
handle_leader_cast(Msg::term(), State::term(), E::election()) -> commonReply()
Called by the leader in response to a leader_cast().
BUG: This has not yet been implemented.
init(Arg::term()) -> {ok, State}
Equivalent to the init/1 function in a gen_server.
surrendered(State::state(), Synch::broadcast(), E::election()) -> {ok, NState}
Called by each candidate when it recognizes another instance as leader.
Strictly speaking, this function is called when the candidate acknowledges a leader and receives a Synch message in return.
Example:
surrendered(OurDict, LeaderDict, E) -> {ok, LeaderDict}.
terminate(Reason::term(), State::state()) -> Void
Equivalent to terminate/2
in a gen_server callback
module.
Generated by EDoc, Dec 25 2007, 02:41:19.