election

Documentation

Overview

Package election provides a wrapper around a subset of the Election functionality of etcd's concurrency package with error handling for common failure scenarios such as lease expiration.

Index

• Variables
• type Client
  • func NewClient(cli *clientv3.Client, prefix string, options ...ClientOption) (*Client, error)
  • func (c *Client) Campaign(ctx context.Context, val string) (<-chan struct{}, error)
  • func (c *Client) Close() error
  • func (c *Client) Leader(ctx context.Context) (string, error)
  • func (c *Client) Observe(ctx context.Context) (<-chan string, error)
  • func (c *Client) Resign(ctx context.Context) error
• type ClientOption
  • func WithSessionOptions(opts ...concurrency.SessionOption) ClientOption

Variables

var (
	// ErrSessionExpired is returned by Campaign() if the underlying session
	// (lease) has expired.
	ErrSessionExpired = errors.New("election: session expired")

	// ErrClientClosed is returned when an election client has been closed and
	// cannot be reused.
	ErrClientClosed = errors.New("election: client has been closed")
)

Types

type Client

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

Client encapsulates a client of etcd-backed leader elections.

func NewClient

func NewClient(cli *clientv3.Client, prefix string, options ...ClientOption) (*Client, error)

NewClient returns an election client based on the given etcd client and participating in elections rooted at the given prefix. Optional parameters can be configured via options, such as configuration of the etcd session TTL.

func (*Client) Campaign

func (c *Client) Campaign(ctx context.Context, val string) (<-chan struct{}, error)

Campaign starts a new campaign for val at the prefix configured at client creation. It blocks until the etcd Campaign call returns, and returns any error encountered or ErrSessionExpired if election.Campaign returned a nil error but was due to the underlying session expiring. If the client is successfully elected with a valid session, a channel is returned which is closed when the session associated with the campaign expires. Callers should watch this channel to determine if their presumed leadership from a nil-error response is no longer valid.

If the session expires while a Campaign() call is blocking, the campaign will be cancelled and return a context.Cancelled error.

If a caller wishes to cancel a current blocking campaign, they must pass a context which they are responsible for cancelling otherwise the call to Campaign() will block indefinitely until the client is elected (or until the associated session expires).

func (*Client) Close

func (c *Client) Close() error

Close closes the client's underlying session and prevents any further campaigns from being started.

func (*Client) Leader

func (c *Client) Leader(ctx context.Context) (string, error)

Leader returns the value proposed by the currently elected leader of the election.

func (*Client) Observe

func (c *Client) Observe(ctx context.Context) (<-chan string, error)

Observe returns a channel which receives that value of the latest leader for the election. The channel is closed when the context is cancelled.

func (*Client) Resign

func (c *Client) Resign(ctx context.Context) error

Resign gives up leadership if the caller was elected. If a current call to Campaign() is ongoing, Resign() will block until that call completes to avoid a race in the concurrency.Election type.

type ClientOption

type ClientOption func(*clientOpts)

ClientOption provides a means of configuring optional parameters for a client.

func WithSessionOptions

func WithSessionOptions(opts ...concurrency.SessionOption) ClientOption

WithSessionOptions sets the options passed to all underlying concurrency.Session instances associated with elections. If the user wishes to override the TTL of sessions, concurrency.WithTTL(ttl) should be passed here.