Functions for conducting elections. More...

This graph shows which files directly or indirectly include 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_t *	election_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 (const election_t *e)
	Get current state of an election. More...

enum election_result	election_count_vote (election_t e, const xmlNode message, 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_internal.h.

Typedef Documentation

◆ election_t

typedef struct election_s election_t

Definition at line 56 of file election_internal.h.

Enumeration Type Documentation

◆ election_result

enum election_result

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_internal.h.

Function Documentation

◆ election_check()

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,out] e Election 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 343 of file election.c.

◆ election_clear_dampening()

void election_clear_dampening ( election_t * e )

Reset any election dampening currently in effect.

Parameters

[in,out] e Election object to clear

Definition at line 724 of file election.c.

◆ election_count_vote()

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

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

Parameters

[in,out]	e	Election object
[in]	message	Election message XML from peer
[in]	can_win	Whether local node is eligible to win

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 534 of file election.c.

◆ election_fini()

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,out] e Election object

Definition at line 165 of file election.c.

◆ election_init()

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]	name	Label for election (for logging)
[in]	uname	Local node's name
[in]	period_ms	How long to wait for all peers to vote
[in]	cb	Function 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 89 of file election.c.

◆ election_remove()

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,out]	e	Election object
[in]	uname	Name of peer to disregard

Definition at line 129 of file election.c.

◆ election_reset()

void election_reset ( election_t * e )

Stop election timer and disregard all votes.

Parameters

[in,out] e Election object

Definition at line 143 of file election.c.

◆ election_state()

enum election_result election_state ( const election_t * e )

Get current state of an election.

Parameters

[in] e Election object

Returns: Current state of

Definition at line 67 of file election.c.

◆ election_timeout_set_period()

void election_timeout_set_period	(	election_t *	e,
		guint	period
	)

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

Parameters

[in,out]	e	Election object
[in]	period	New timeout

Definition at line 205 of file election.c.

◆ election_timeout_stop()

void election_timeout_stop ( election_t * e )

Stop an election's timer, if running.

Parameters

[in,out] e Election object

Definition at line 191 of file election.c.

◆ election_vote()

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,out] e Election 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 290 of file election.c.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ election_t

Enumeration Type Documentation

◆ election_result

Function Documentation

◆ election_check()

◆ election_clear_dampening()

◆ election_count_vote()

◆ election_fini()

◆ election_init()

◆ election_remove()

◆ election_reset()

◆ election_state()

◆ election_timeout_set_period()

◆ election_timeout_stop()

◆ election_vote()