elector (elector v0.3.3)

Elector - Distributed Leader Election for Erlang/OTP

This is the main API module for the Elector application. Elector automatically detects all nodes in a distributed Erlang cluster and chooses a leader node. Elections are started automatically when the application starts or when nodes join/leave the cluster.

## Quick Start

The elector application must be started before calling any functions:

  % Start elector application
  ok = application:start(elector).
 
  % Check if current node is leader
  {ok, IsLeader} = elector:is_leader().
 
  % Get the current leader node
  {ok, LeaderNode} = elector:get_leader().
 
  % Manually trigger an election
  {ok, election_started} = elector:elect().

## Automatic Elections

When elector is started, it handles elections automatically: - On application startup - When new nodes join the cluster - When existing nodes leave the cluster

You can also trigger elections manually using elect/0 or elect_sync/0.

For detailed configuration and setup instructions, see the [Getting Started guide](readme.html).

Summary

Types

leader_node/0

Functions

clear_leader()

Clears the leader node and sets it to undefined.

elect()

Starts an election process asynchronously.

elect_sync()

Starts an election synchronously.

get_leader()

Returns the current leader node's name.

is_leader()

Checks if the current node is the elected leader.

Types

leader_node/0

-type leader_node() :: node() | undefined.

Functions

clear_leader()

-spec clear_leader() -> {ok, leader_cleared}.

Clears the leader node and sets it to undefined.

elect()

-spec elect() ->
               {ok, async_election_started} |
               {error, quorum_size_not_met} |
               {error, election_commission_not_up}.

Starts an election process asynchronously.

This function triggers a new leader election across the cluster. The election runs in the background and doesn't block the caller.

## Returns

- {ok, async_election_started} - Election started successfully - {error, quorum_size_not_met} - Not enough nodes in cluster - {error, election_commission_not_up} - Election service unavailable

## Examples

  case elector:elect() of
      {ok, async_election_started} ->
          io:format("Election started~n");
      {error, Reason} ->
          io:format("Election failed: ~p~n", [Reason])
  end.

elect_sync()

-spec elect_sync() ->
                    {ok, leader_node()} |
                    {error, quorum_size_not_met} |
                    {error, election_commission_not_up}.

Starts an election synchronously.

get_leader()

-spec get_leader() -> {ok, node()} | {error, leader_node_not_set}.

Returns the current leader node's name.

## Examples

  case elector:get_leader() of
      {ok, LeaderNode} ->
          io:format("Leader is: ~p~n", [LeaderNode]);
      {error, leader_node_not_set} ->
          io:format("No leader elected yet~n")
  end.

is_leader()

-spec is_leader() -> {ok, boolean()} | {error, leader_node_not_set}.

Checks if the current node is the elected leader.

Returns {ok, true} if this node is currently the leader, {ok, false} if another node is the leader, or an error if no leader has been elected yet.

## Examples

  % Check leadership status
  case elector:is_leader() of
      {ok, true} ->
          io:format("This node is the leader~n");
      {ok, false} ->
          io:format("This node is not the leader~n");
      {error, leader_node_not_set} ->
          io:format("No leader elected yet~n")
  end.