Module test_cb

Example callback module for the gen_leader behaviour.

Behaviours: gen_leader.

Authors: Ulf Wiger (ulf.wiger@ericsson.com), Thomas Arts (thomas.arts@ituniv.se).

Description

Example callback module for the gen_leader behaviour.

This particular callback module implements a global dictionary, and is the back-end for the gdict module.

Data Types

broadcast()

broadcast() = term()

Whatever the leader decides to broadcast to the candidates.

commonReply()

commonReply() = {ok, state()} | {ok, broadcast(), state()} | {stop, reason(), state()}

Common set of valid replies from most callback functions.

dictionary()

dictionary() = tuple()

Same as from dict:new(); used in this module as State.

election()

election() = tuple()

Opaque state of the gen_leader behaviour.

node()

node() = atom()

A node name.

reason()

reason() = term()

Error information.

state()

state() = dictionary()

Internal server state; In the general case, it can be any term.

Function Index

code_change/4Similar to code_change/3 in a gen_server callback module, with the exception of the added argument E.
elected/2Called by the leader it is elected leader, and each time a candidate recognizes the leader.
from_leader/3Called by each candidate in response to a message from the leader.
handle_DOWN/3Called by the leader when it detects loss of a candidate node.
handle_call/3Equivalent to Mod:handle_call/3 in a gen_server.
handle_cast/2Equivalent to Mod:handle_call/3 in a gen_server, except (NOTE) for the possible return values.
handle_info/2Equivalent to Mod:handle_info/3 in a gen_server, except (NOTE) for the possible return values.
handle_leader_call/4Called by the leader in response to a leader_call().
handle_leader_cast/3Called by the leader in response to a leader_cast().
init/1Equivalent to the init/1 function in a gen_server.
surrendered/3Called by each candidate when it recognizes another instance as leader.
terminate/2Equivalent to terminate/2 in a gen_server callback module.

Function Details

code_change/4

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

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

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

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

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

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

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

init(Arg::term()) -> {ok, State}

Equivalent to the init/1 function in a gen_server.

surrendered/3

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

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.