lib/gen_leader/README

   1
   2
   3 Leader election behaviour (gen_leader)
   4 --------------------------------------
   5 Vsn     : 1.0
   6 Date    : 2003-04-03
   7
   8 Authors: Thomas Arts <thomas.arts@ituniv.se>
   9          Ulf Wiger <ulf.wiger@ericsson.com>
  10
  11
  12 This application implements a leader election behaviour modeled after
  13 gen_server. This behaviour intends to make it reasonably
  14 straightforward to implement a fully distributed server with
  15 master-slave semantics.
  16
  17 The gen_leader behaviour supports nearly everything that gen_server
  18 does (some functions, such as multicall() and the internal timeout,
  19 have been removed), and adds a few callbacks and API functions to
  20 support leader election etc.
  21
  22 Also included is an example program, a global dictionary, based
  23 on the modules gen_leader and dict. The callback implementing the
  24 global dictionary is called 'test_cb', for no particularly logical
  25 reason.
  26
  27
  28 Interface functions:
  29
  30 start(Name, CandidateNodes, Workers, Module, Arg, Options)
  31 start_link(Name, CandidateNodes, Workers, Module, Arg, Options)
  32    -> {ok,Pid} | error()
  33
  34    Name : atom()        Locally registered name of the server
  35                         Note that {global,Name} is not supported,
  36                         since the idea is to have one instance of
  37                         the server on each node.
  38
  39    CandidateNodes : [atom()]
  40                         List of nodes that can become master.
  41                         Currently, the programmer must ensure that
  42                         this list is the same on all nodes.
  43
  44    Workers : [atom()]   List of nodes that will run an instance of
  45                         the server, but cannot be considered for the
  46                         master role.
  47
  48    Module : atom()      Name of the callback module.
  49
  50    Arg : term()         Argument passed to the Mod:init/1 function
  51
  52    Options : [term()]   Same as the gen_server options.
  53
  54
  55 call(Server, Request)
  56 call(Server, Request, Timeout)
  57 cast(Server, Message)
  58 reply(Client, Reply)
  59
  60    Identical to the gen_server counterparts.
  61
  62
  63 leader_call(Name, Request)
  64 leader_call(Name, Request, Timeout)
  65    -> term()
  66
  67    Performs a gen_server-like call to the leader server. The call is
  68    made via the local server, and is buffered until a leader is found.
  69    If the leader dies during the call, the function exits with reason
  70    'leader_died'.
  71
  72
  73 leader_cast(Name, Msg)
  74    -> ok.
  75
  76    Performs a gen_server-like cast to the leader server. Otherwise
  77    Semantically the same as gen_server:cast/2.
  78
  79
  80 Callbacks:
  81
  82   (valid for all nodes)
  83
  84 Module:init(Arg) -> {ok, State} | {stop, Reason} | ignore
  85
  86    Identical to the gen_server counterpart.
  87
  88 Module:handle_call(Request, From, State) ->
  89    {reply, Reply, NState}
  90    | {ok, NState}
  91    | {noreply, NState}
  92    | {stop, Reason, NState}
  93    | {stop, Reply, Reason, NState}
  94
  95    Election : opaque()
  96
  97   This function is called in response to a gen_leader:call/[2,3],
  98   which always goes to the local instance of the server.
  99   {ok, NState} is synonym with {noreply, NState}.
 100
 101 Module:handle_cast(Message, State) ->
 102    {ok, NState}
 103    | {stop, Reason, NState}
 104
 105   This function is called in response to a gen_leader:cast/2,
 106   which always sends a message to the local instance of the server.
 107
 108 Module:handle_info(Message, State) ->
 109    {ok, NState}
 110    | {stop, Reason, NState}
 111
 112   This function is called in response to any incoming message not
 113   recognized as a call, cast, leader_call, leader_cast, internal
 114   leader negotiation message or system message.
 115
 116 Module:terminate(Reason, State) -> void()
 117
 118   This function is called before terminating the server instance.
 119   The return value is ignored. Note that this function is not
 120   called if the server dies due to an EXIT message (if the server
 121   is not trapping exits).
 122
 123 Module:code_change(OldVsn, State, Election, Extra) ->
 124    {ok, NState}
 125    | {ok, NState, NElection}
 126
 127   This function is called when the server should update its internal
 128   state due to code replacement. See SASL User's Guide for more
 129   information. Note that it is possible here to also update the
 130   otherwise opaque Election variable. This could be one way to
 131   add candidate nodes in service.
 132
 133   (only called on the leader node)
 134
 135 Module:elected(State, Election) -> {ok,Synch,NewState}.
 136    State : term()
 137    Synch : term()
 138    Election : opaque()
 139
 140    This function is called when a leader is first elected, and each
 141    time another server has surrendered to the current leader.
 142
 143    Synch will be passed along to the server(s) that surrendered, and
 144    can e.g. be used to maintain a replicated state.
 145
 146    Election is opaque, and can be used to call some helper functions
 147    (see below)
 148
 149 Module:handle_DOWN(Node, State, Election)
 150    -> {ok,NewState} | {ok,Broadcast,NewState}.
 151
 152 Module:handle_leader_call(Request, From, State, E) ->
 153    {reply, Reply, NState}
 154    | {reply, Reply, Broadcast, NState}
 155    | {ok, NState}
 156    | {noreply, NState}
 157    | {stop, Reason, NState}
 158    | {stop, Reason, Reply, NState}
 159
 160    This function is called on the leader node in response to a
 161    gen_leader:leader_call/[2,3]. It is similar to handle_call/3
 162    for a gen_server callback, but also allows the leader to send
 163    a broadcast message to all other instances of the server.
 164    The return value {ok, NState} is synonym with {noreply,NState}.
 165
 166    Note that when using gen_leader:reply/2, it is necessary to
 167    use gen_leader:reply(From, {leader,reply,Reply}). Otherwise,
 168    the reply will not reach the client.
 169
 170 BUG: Module:handle_leader_cast/3 is never called.
 171
 172
 173   (only called on non-leader nodes)
 174
 175 Module:surrendered(State, Synch, Election) -> {ok, NewState}.
 176
 177    This function is called whenever a new leader is elected, or
 178    a new server instance recognizes the current leader. Synch is
 179    the data returned from the corresponding elected/2 call on the
 180    leader node.
 181
 182 Module:from_leader(Broadcast, State, Election) ->
 183    {ok,NState}
 184    | {stop, Reason, NState}
 185
 186    This function is called on all non-leader nodes in response to
 187    a broadcast message from the leader (e.g. triggered in
 188    handle_leader_call/4).
 189
 190
 191
 192 Query functions for the callback module:
 193
 194
 195   For the functions below, the Election argument is passed along
 196   in the callback functions. The contents of this variable are
 197   to be considered internal to the gen_leader module, and should
 198   not be inspected other than through the use of these helper functions.
 199
 200 alive(Election) -> [atom()]
 201
 202    Returns a list of nodes where an instance of the server is running.
 203
 204 down(Election) -> [atom()]
 205
 206    Returns a list of nodes currently down.
 207
 208 candidates(Election) -> [atom()]
 209
 210    Returns a list of known candidate nodes.
 211
 212 workers(Election) -> [atom()]
 213
 214    Returns a list of known worker nodes.
 215