leadership

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 9, 2015 License: Apache-2.0 Imports: 4 Imported by: 0

README

Leadership: Distributed Leader Election for Clustered Environments.

Leadership is a library for a cluster leader election on top of a distributed Key/Value store.

It's built using Swarm's pkg/store and is designed to work across multiple storage backends.

You can use leadership with Consul, etcd and Zookeeper.

// Create a store using pkg/store.
client, err := store.NewStore("consul", []string{"127.0.0.1:8500"}, &store.Config{})
if err != nil {
	panic(err)
}

underwood := leadership.NewCandidate(client, "service/swarm/leader", "underwood")
electedCh, _ := underwood.RunForElection()

for isElected := range electedCh {
	// This loop will run every time there is a change in our leadership
	// status.

	if isElected {
		// We won the election - we are now the leader.
		// Let's do leader stuff, for example, sleep for a while.
		log.Printf("I won the election! I'm now the leader")
		time.Sleep(10 * time.Second)

		// Tired of being a leader? You can resign anytime.
		candidate.Resign()
	} else {
		// We lost the election but are still running for leadership.
		// `elected == false` is the default state and is the first event
		// we'll receive from the channel. After a successful election,
		// this event can get triggered if someone else steals the
		// leadership or if we resign.

		log.Printf("Lost the election, let's try another time")
	}
}

It is possible to follow an election in real-time and get notified whenever there is a change in leadership:

follower := leadership.NewFollower(client, "service/swarm/leader")
leaderCh, _ := follower.FollowElection()
for leader := <-leaderCh {
	// Leader is a string containing the value passed to `NewCandidate`.
	log.Printf("%s is now the leader", leader)
}

A typical use case for this is to be able to always send requests to the current leader.

Fault tolerance

Leadership returns an error channel for Candidates and Followers that you can use to be resilient to failures. For example, if the watch on the leader key fails because the store becomes unavailable, you can retry the process later.

func participate() {
    // Create a store using pkg/store.
    client, err := store.NewStore("consul", []string{"127.0.0.1:8500"}, &store.Config{})
    if err != nil {
        panic(err)
    }

    waitTime := 10 * time.Second
    underwood := leadership.NewCandidate(client, "service/swarm/leader", "underwood")

    go func() {
        for {
            run(underwood)
            time.Sleep(waitTime)
            // retry
        }
    }
}

func run(candidate *leadership.Candidate) {
    electedCh, errCh := candidate.RunForElection()
    for {
        select {
            case elected := <-electedCh:
            if isElected {
                // Do something
            } else {
                // Do something else
            }

            case err := <-errCh:
                log.Error(err)
                return
    }
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Candidate

type Candidate struct {
	// contains filtered or unexported fields
}

Candidate runs the leader election algorithm asynchronously

func NewCandidate

func NewCandidate(client store.Store, key, node string, ttl time.Duration) *Candidate

NewCandidate creates a new Candidate

func (*Candidate) IsLeader

func (c *Candidate) IsLeader() bool

IsLeader returns true if the candidate is currently a leader.

func (*Candidate) Resign

func (c *Candidate) Resign()

Resign forces the candidate to step-down and try again. If the candidate is not a leader, it doesn't have any effect. Candidate will retry immediately to acquire the leadership. If no-one else took it, then the Candidate will end up being a leader again.

func (*Candidate) RunForElection

func (c *Candidate) RunForElection() (<-chan bool, <-chan error)

RunForElection starts the leader election algorithm. Updates in status are pushed through the ElectedCh channel.

ElectedCh is used to get a channel which delivers signals on acquiring or losing leadership. It sends true if we become the leader, and false if we lose it.

func (*Candidate) Stop

func (c *Candidate) Stop()

Stop running for election.

type Follower

type Follower struct {
	// contains filtered or unexported fields
}

Follower can follow an election in real-time and push notifications whenever there is a change in leadership.

func NewFollower

func NewFollower(client store.Store, key string) *Follower

NewFollower creates a new follower.

func (*Follower) FollowElection

func (f *Follower) FollowElection() (<-chan string, <-chan error)

FollowElection starts monitoring the election.

func (*Follower) Leader

func (f *Follower) Leader() string

Leader returns the current leader.

func (*Follower) Stop

func (f *Follower) Stop()

Stop stops monitoring an election.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL