pacemaker  2.0.4-2deceaa
Scalable High-Availability cluster resource manager
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Typedefs | Enumerations | Functions
election.h File Reference

Functions for conducting elections. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct election_s election_t
 

Enumerations

enum  election_result {
  election_start = 0, election_in_progress, election_lost, election_won,
  election_error
}
 

Functions

void election_fini (election_t *e)
 Free an election object. More...
 
void election_reset (election_t *e)
 Stop election timer and disregard all votes. More...
 
election_telection_init (const char *name, const char *uname, guint period_ms, GSourceFunc cb)
 Create a new election object. More...
 
void election_timeout_set_period (election_t *e, guint period_ms)
 Change an election's timeout (restarting timer if running) More...
 
void election_timeout_stop (election_t *e)
 Stop an election's timer, if running. More...
 
void election_vote (election_t *e)
 Start a new election by offering local node's candidacy. More...
 
bool election_check (election_t *e)
 Check whether local node has won an election. More...
 
void election_remove (election_t *e, const char *uname)
 Disregard any previous vote by specified peer. More...
 
enum election_result election_state (election_t *e)
 
enum election_result election_count_vote (election_t *e, xmlNode *vote, bool can_win)
 Process an election message (vote or no-vote) from a peer. More...
 
void election_clear_dampening (election_t *e)
 Reset any election dampening currently in effect. More...
 

Detailed Description

Functions for conducting elections.

An election is useful for a daemon that runs on all nodes but needs any one instance to perform a special role.

Elections are closely tied to the cluster peer cache. Peers in the cache that are active members are eligible to vote. Elections are named for logging purposes, but only one election may exist at any time, so typically an election would be created at daemon start-up and freed at shutdown.

Pacemaker's election procedure has been heavily adapted from the Invitation Algorithm variant of the Garcia-Molina Bully Algorithm:

https://en.wikipedia.org/wiki/Bully_algorithm

Elections are conducted via cluster messages. There are two types of messages: a "vote" is a declaration of the voting node's candidacy, and is always broadcast; a "no-vote" is a concession by the responding node, and is always a reply to the preferred node's vote. (These correspond to "invite" and "accept" in the traditional algorithm.)

A vote together with any no-vote replies to it is considered an election round. Rounds are numbered with a simple counter unique to each node (this would be the group number in the traditional algorithm). Concurrent election rounds are possible.

An election round is started when any node broadcasts a vote. When a node receives another node's vote, it compares itself against the sending node according to certain metrics, and either starts a new round (if it prefers itself) or replies to the other node with a no-vote (if it prefers that node).

If a node receives no-votes from all other active nodes, it declares itself the winner. The library API does not notify other nodes of this; callers must implement that if desired.

Definition in file election.h.

Typedef Documentation

typedef struct election_s election_t

Definition at line 56 of file election.h.

Enumeration Type Documentation

Possible election states

Enumerator
election_start 
election_in_progress 

new election needed

election_lost 

election started but not all peers have voted

election_won 

local node lost most recent election

election_error 

local node won most recent election

Definition at line 59 of file election.h.

Function Documentation

bool election_check ( election_t e)

Check whether local node has won an election.

If all known peers have sent no-vote messages, stop the election timer, set the election state to won, and call any registered win callback.

Parameters
[in]eElection object
Returns
TRUE if local node has won, FALSE otherwise
Note
If all known peers have sent no-vote messages, but the election owner does not call this function, the election will not be won (and the callback will not be called) until the election times out.
This should be called when election_count_vote() returns election_in_progress.

Definition at line 336 of file election.c.

void election_clear_dampening ( election_t e)

Reset any election dampening currently in effect.

Parameters
[in]eElection object to clear

Definition at line 715 of file election.c.

enum election_result election_count_vote ( election_t e,
xmlNode *  message,
bool  can_win 
)

Process an election message (vote or no-vote) from a peer.

Parameters
[in]eElection object
[in]voteElection message XML from peer
[in]can_winWhether to consider the local node eligible for winning
Returns
Election state after new vote is considered
Note
If the peer message is a vote, and we prefer the peer to win, this will send a no-vote reply to the peer.
The situations "we lost to this vote" from "this is a late no-vote after we've already lost" both return election_lost. If a caller needs to distinguish them, it should save the current state before calling this function, and then compare the result.

Definition at line 526 of file election.c.

void election_fini ( election_t e)

Free an election object.

Free all memory associated with an election object, stopping its election timer (if running).

Parameters
[in]eElection object

Definition at line 159 of file election.c.

election_t* election_init ( const char *  name,
const char *  uname,
guint  period_ms,
GSourceFunc  cb 
)

Create a new election object.

Every node that wishes to participate in an election must create an election object. Typically, this should be done once, at start-up. A caller should only create a single election object.

Parameters
[in]nameLabel for election (for logging)
[in]unameLocal node's name
[in]period_msHow long to wait for all peers to vote
[in]cbFunction to call if local node wins election
Returns
Newly allocated election object on success, NULL on error
Note
The caller is responsible for freeing the returned value using election_fini().

Definition at line 83 of file election.c.

void election_remove ( election_t e,
const char *  uname 
)

Disregard any previous vote by specified peer.

This discards any recorded vote from a specified peer. Election users should call this whenever a voting peer becomes inactive.

Parameters
[in]eElection object
[in]unameName of peer to disregard

Definition at line 123 of file election.c.

void election_reset ( election_t e)

Stop election timer and disregard all votes.

Parameters
[in]eElection object

Definition at line 137 of file election.c.

enum election_result election_state ( election_t e)

Definition at line 58 of file election.c.

void election_timeout_set_period ( election_t e,
guint  period 
)

Change an election's timeout (restarting timer if running)

Parameters
[in]eElection object
[in]periodNew timeout

Definition at line 199 of file election.c.

void election_timeout_stop ( election_t e)

Stop an election's timer, if running.

Parameters
[in]eElection object

Definition at line 185 of file election.c.

void election_vote ( election_t e)

Start a new election by offering local node's candidacy.

Broadcast a "vote" election message containing the local node's ID, (incremented) election counter, and uptime, and start the election timer.

Parameters
[in]eElection object
Note
Any nodes agreeing to the candidacy will send a "no-vote" reply, and if all active peers do so, or if the election times out, the local node wins the election. (If we lose to any peer vote, we will stop the timer, so a timeout means we did not lose – either some peer did not vote, or we did not call election_check() in time.)

Definition at line 283 of file election.c.