election

Documentation

Overview

Package election provides leader election built on claim + fencing semantics.

Index

• Variables
• type Config
• type Election
  • func Join(parent context.Context, cfg Config) (*Election, error)
  • func (e *Election) Close(ctx context.Context) error
  • func (e *Election) Events() <-chan Event
  • func (e *Election) IsLeader() bool
  • func (e *Election) Resign(ctx context.Context) error
  • func (e *Election) Token() uint64
  • func (e *Election) Transfer(ctx context.Context, _ string) error
• type Event
• type EventType
• type FencedLock
• type Gate

Variables

var (
	ErrClosed    = errors.New("election: closed")
	ErrNotLeader = errors.New("election: not leader")
	ErrDenied    = errors.New("election: denied")
)

Types

type Config

type Config struct {
	Name          string
	ParticipantID string
	Lock          FencedLock
	Gate          Gate
	RenewEvery    time.Duration
	EventBuffer   int // bounded; default 16
	Clock         func() time.Time
}

Config configures an Election.

type Election

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

Election is a single named leadership contest.

func Join

func Join(parent context.Context, cfg Config) (*Election, error)

Join starts participating; may become leader when the claim is acquired.

func (*Election) Close

func (e *Election) Close(ctx context.Context) error

Close stops the election loop and resigns if leading.

func (*Election) Events

func (e *Election) Events() <-chan Event

Events returns a bounded receive-only channel (drops on overflow).

func (*Election) IsLeader

func (e *Election) IsLeader() bool

IsLeader reports local leadership belief (always confirm via token fencing for work).

func (*Election) Resign

func (e *Election) Resign(ctx context.Context) error

Resign releases leadership if held.

func (*Election) Token

func (e *Election) Token() uint64

Token returns the fencing token when leading.

func (*Election) Transfer

func (e *Election) Transfer(ctx context.Context, _ string) error

Transfer resigns so another participant may acquire (cooperative).

type Event

type Event struct {
	Type     EventType
	Election string
	Leader   string
	Token    uint64
	Time     time.Time
	Err      string
}

Event is emitted on leadership changes.

type EventType

type EventType string

EventType classifies election events.

const (
	EventJoined      EventType = "joined"
	EventLeading     EventType = "leading"
	EventFollow      EventType = "following"
	EventResigned    EventType = "resigned"
	EventTransferred EventType = "transferred"
	EventLost        EventType = "lost"
)

type FencedLock

type FencedLock interface {
	Acquire(ctx context.Context, claim string) (token uint64, err error)
	Release(ctx context.Context, claim string, token uint64) error
	Renew(ctx context.Context, claim string, token uint64) error
}

FencedLock is the claim/fencing adapter (implemented by Runtime).

type Gate

type Gate interface {
	AllowElection(name string) error
}

Gate may deny join (quarantine / lockdown).