election

Documentation

Overview

Package election provides implementation of master election and tracking, as well as interface for plugging in a custom underlying mechanism.

Index

• Constants
• Variables
• func HeldInfo(held []string, ids []string) string
• type Factory
• type MasterElection
• type MasterTracker
  • func NewMasterTracker(ids []string, notify func(id string, isMaster bool)) *MasterTracker
  • func (mt *MasterTracker) Count() int
  • func (mt *MasterTracker) Held() []string
  • func (mt *MasterTracker) IDs() []string
  • func (mt *MasterTracker) Set(id string, val bool)
  • func (mt *MasterTracker) String() string
• type NoopElection
  • func (ne *NoopElection) Close(ctx context.Context) error
  • func (ne *NoopElection) GetCurrentMaster(ctx context.Context) (string, error)
  • func (ne *NoopElection) IsMaster(ctx context.Context) (bool, error)
  • func (ne *NoopElection) Resign(ctx context.Context) error
  • func (ne *NoopElection) Start(ctx context.Context) error
  • func (ne *NoopElection) WaitForMastership(ctx context.Context) error
• type NoopFactory
  • func (nf NoopFactory) NewElection(ctx context.Context, resourceID string) (MasterElection, error)
• type Resignation
  • func (r *Resignation) Execute(ctx context.Context)
• type Runner
  • func NewRunner(id string, cfg *RunnerConfig, tracker *MasterTracker, ...) *Runner
  • func (er *Runner) Run(ctx context.Context, pending chan<- Resignation)
  • func (er *Runner) ShouldResign(masterSince time.Time) bool
• type RunnerConfig

Constants

const (
	MinPreElectionPause    = 10 * time.Millisecond
	MinMasterCheckInterval = 50 * time.Millisecond
	MinMasterHoldInterval  = 10 * time.Second
)

Minimum values for configuration intervals.

Variables

var ErrNoMaster = errors.New("no master")

ErrNoMaster indicates that there is currently no master elected.

Functions

func HeldInfo

func HeldInfo(held []string, ids []string) string

HeldInfo produces a textual description of the set of held IDs, compared to a complete set of IDs.

Types

type Factory

type Factory interface {
	NewElection(ctx context.Context, resourceID string) (MasterElection, error)
}

Factory encapsulates the creation of a MasterElection instance for a resourceID. TreeID may be used as a resourceID.

type MasterElection

type MasterElection interface {
	// Start kicks off this instance's participation in master election.
	Start(context.Context) error
	// WaitForMastership blocks until the current instance is the master.
	WaitForMastership(context.Context) error
	// IsMaster returns whether the current instance is the master.
	IsMaster(context.Context) (bool, error)
	// Resign releases mastership, and stops this instance from participating in
	// the master election.
	Resign(context.Context) error
	// Close releases all the resources associated with this MasterElection.
	Close(context.Context) error
	// GetCurrentMaster returns the instance ID of the current elected master, if
	// any. Implementations should allow election participants to specify their
	// instance ID string, participants should ensure that it is unique to them.
	// If there is currently no master, ErrNoMaster will be returned.
	GetCurrentMaster(context.Context) (string, error)
}

MasterElection provides operations for determining if a local instance is the current master for a particular election.

type MasterTracker

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

MasterTracker tracks the current mastership state across multiple IDs.

func NewMasterTracker

func NewMasterTracker(ids []string, notify func(id string, isMaster bool)) *MasterTracker

NewMasterTracker creates a new MasterTracker instance to track the mastership status for the given set of ids.

func (*MasterTracker) Count

func (mt *MasterTracker) Count() int

Count returns the number of IDs for which we are currently master.

func (*MasterTracker) Held

func (mt *MasterTracker) Held() []string

Held returns a (sorted) list of the IDs for which we are currently master.

func (*MasterTracker) IDs

func (mt *MasterTracker) IDs() []string

IDs returns a (sorted) list of the IDs that we are currently tracking.

func (*MasterTracker) Set

func (mt *MasterTracker) Set(id string, val bool)

Set changes the tracked mastership status for the given id. This method should be called exactly once for each state transition.

func (*MasterTracker) String

func (mt *MasterTracker) String() string

String returns a textual decription of the current mastership status.

type NoopElection

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

NoopElection is a stub implementation that tells every instance that it is master.

func (*NoopElection) Close

func (ne *NoopElection) Close(ctx context.Context) error

Close permanently stops the mastership election process.

func (*NoopElection) GetCurrentMaster

func (ne *NoopElection) GetCurrentMaster(ctx context.Context) (string, error)

GetCurrentMaster returns ne.instanceID

func (*NoopElection) IsMaster

func (ne *NoopElection) IsMaster(ctx context.Context) (bool, error)

IsMaster returns whether the current instance is master.

func (*NoopElection) Resign

func (ne *NoopElection) Resign(ctx context.Context) error

Resign releases mastership.

func (*NoopElection) Start

func (ne *NoopElection) Start(ctx context.Context) error

Start kicks off the process of mastership election.

func (*NoopElection) WaitForMastership

func (ne *NoopElection) WaitForMastership(ctx context.Context) error

WaitForMastership blocks until the current instance is master for this election.

type NoopFactory

type NoopFactory struct {
	InstanceID string
}

NoopFactory creates NoopElection instances.

func (NoopFactory) NewElection

func (nf NoopFactory) NewElection(ctx context.Context, resourceID string) (MasterElection, error)

NewElection creates a specific NoopElection instance.

type Resignation

type Resignation struct {
	ID string
	// contains filtered or unexported fields
}

Resignation indicates that a master should explicitly resign mastership, by invoking the Execute() method at a point where no master-related activity is ongoing.

func (*Resignation) Execute

func (r *Resignation) Execute(ctx context.Context)

Execute performs the pending deliberate resignation for an election runner.

type Runner

type Runner struct {
	// Allow the user to store a Cancel function with the runner for convenience.
	Cancel context.CancelFunc
	// contains filtered or unexported fields
}

Runner controls a continuous election process.

func NewRunner

func NewRunner(id string, cfg *RunnerConfig, tracker *MasterTracker, cancel context.CancelFunc, el MasterElection) *Runner

NewRunner builds a new election Runner instance with the given configuration. On calling Run(), the provided election will be continuously monitored and mastership changes will be notified to the provided MasterTracker instance.

func (*Runner) Run

func (er *Runner) Run(ctx context.Context, pending chan<- Resignation)

Run performs a continuous election process. It runs continuously until the context is canceled or an internal error is encountered.

func (*Runner) ShouldResign

func (er *Runner) ShouldResign(masterSince time.Time) bool

ShouldResign randomly decides whether this runner should resign mastership.

type RunnerConfig

type RunnerConfig struct {
	// PreElectionPause is the maximum interval to wait before starting a
	// mastership election for a particular log.
	PreElectionPause time.Duration
	// MasterCheckInterval is the interval between checks that we still
	// hold mastership for a log.
	MasterCheckInterval time.Duration
	// MasterHoldInterval is the minimum interval to hold mastership for.
	MasterHoldInterval time.Duration
	// ResignOdds gives the chance of resigning mastership after each
	// check interval, as the N for 1-in-N.
	ResignOdds int

	TimeSource util.TimeSource
}

RunnerConfig describes the parameters for an election Runner.