juju: github.com/juju/juju/core/leadership Index | Files | Directories

package leadership

import "github.com/juju/juju/core/leadership"

Package leadership holds code pertaining to application leadership in juju. It's expected to grow as we're able to extract (e.g.) the Ticket and Tracker interfaces from worker/leadership; and quite possible the implementations themselves; but that'll have to wait until it can all be expressed without reference to non-core code.


Package Files



var ErrBlockCancelled = errors.New("waiting for leadership cancelled by client")

ErrBlockCancelled is returned from BlockUntilLeadershipReleased if the client cancels the request by closing the cancel channel.

var ErrClaimDenied = errors.New("leadership claim denied")

ErrClaimDenied is the error which will be returned when a leadership claim has been denied.

var ErrClaimNotHeld = errors.New("leadership lease not held")

ErrClaimNotHeld is the error which will be returned when a leadership lease is not held.

func IsNotLeaderError Uses

func IsNotLeaderError(err error) bool

IsNotLeaderError returns whether this error represents a token check that failed because the unit in question wasn't the leader.

func NewNotLeaderError Uses

func NewNotLeaderError(unit, application string) error

NewNotLeaderError returns an error indicating that this unit is not the leader of that application.

type Checker Uses

type Checker interface {

    // LeadershipCheck returns a Token representing the supplied unit's
    // application leadership. The existence of the token does not imply
    // its accuracy; you need to Check() it.
    // This method returns a token that accepts a *[]txn.Op, into which
    // it will (on success) copy mgo/txn operations that can be used to
    // verify the unit's continued leadership as part of another txn.
    LeadershipCheck(applicationId, unitId string) Token

Checker exposes leadership testing capabilities.

type Claimer Uses

type Claimer interface {

    // ClaimLeadership claims leadership of the named application on behalf of the
    // named unit. If no error is returned, leadership will be guaranteed for
    // at least the supplied duration from the point when the call was made.
    ClaimLeadership(applicationId, unitId string, duration time.Duration) error

    // BlockUntilLeadershipReleased blocks until the named application is known
    // to have no leader, in which case it returns no error; or until the
    // manager is stopped, in which case it will fail.
    BlockUntilLeadershipReleased(applicationId string, cancel <-chan struct{}) (err error)

Claimer exposes leadership acquisition capabilities.

type Pinner Uses

type Pinner interface {

    // PinLeadership ensures that the leadership of the input application will
    // not expire. The input entity records the party responsible for the
    // pinning operation.
    PinLeadership(applicationId string, entity string) error

    // UnpinLeadership reverses a PinLeadership operation for the same
    // application and entity. Normal expiry behaviour is restored when no
    // entities remain with pins for the application.
    UnpinLeadership(applicationId string, entity string) error

    // PinnedLeadership returns a map keyed on pinned application names,
    // with entities that require the application's pinned behaviour.
    PinnedLeadership() map[string][]string

Pinner describes methods used to manage suspension of application leadership expiry. All methods should be idempotent.

type Reader Uses

type Reader interface {

    // Leaders returns all application leaders in the current model.
    // TODO (manadart 2019-02-27): The return in this signature includes error
    // in order to support state.ApplicationLeaders for legacy leases.
    // When legacy leases are removed, so can the error return.
    Leaders() (map[string]string, error)

Reader describes the capability to read the current state of leadership.

type Revoker Uses

type Revoker interface {
    // RevokeLeadership revokes leadership of the named application
    // on behalf of the named unit.
    RevokeLeadership(applicationId, unitId string) error

Claimer exposes leadership revocation capabilities.

type Ticket Uses

type Ticket interface {

    // Wait returns true if its Tracker is prepared to guarantee leadership
    // for some period from the ticket request. The guaranteed duration depends
    // upon the Tracker.
    Wait() bool

    // Ready returns a channel that will be closed when a result is available
    // to Wait(), and is helpful for clients that want to select rather than
    // block on long-waiting tickets.
    Ready() <-chan struct{}

Ticket is used to communicate leadership status to Tracker clients.

type Token Uses

type Token interface {

    // Check returns an error if the condition it embodies no longer
    // holds.  If you pass a non-nil trapdoorKey value into Check, it
    // must be a pointer to data of the correct type, into which the
    // token's content will be copied.
    // The "correct type" is implementation-specific, and no implementation
    // is obliged to accept any non-nil parameter; but methods that return
    // Tokens should explain whether, and how, they will expose their content.
    // In practice, most Token implementations will likely expect *[]txn.Op,
    // so that they can be used to gate mgo/txn-based state changes.
    // If a non-nil trapdoorKey value is passed, attempt should be how
    // many times this check has been tried previously (for example,
    // in a buildTxn function it'll be the transaction attempt). This
    // enables the token to generate different ops for the second
    // attempt (the raft lease implementation uses this).
    Check(attempt int, trapdoorKey interface{}) error

Token represents a unit's leadership of its application.

type Tracker Uses

type Tracker interface {

    // ApplicationName returns the name of the application for which leadership claims
    // are made.
    ApplicationName() string

    // ClaimDuration returns the duration for which a Ticket's true Wait result
    // is guaranteed valid.
    ClaimDuration() time.Duration

    // ClaimLeader will return a Ticket which, when Wait()ed for, will return
    // true if leadership is guaranteed for at least the tracker's duration from
    // the time the ticket was issued. Leadership claims should be resolved
    // relatively quickly.
    ClaimLeader() Ticket

    // WaitLeader will return a Ticket which, when Wait()ed for, will block
    // until the tracker attains leadership.
    WaitLeader() Ticket

    // WaitMinion will return a Ticket which, when Wait()ed for, will block
    // until the tracker's future leadership can no longer be guaranteed.
    WaitMinion() Ticket

Tracker allows clients to discover current leadership status by attempting to claim it for themselves.

type TrackerWorker Uses

type TrackerWorker interface {

TrackerWorker represents a leadership tracker worker.


mocksPackage mocks is a generated GoMock package.

Package leadership imports 4 packages (graph) and is imported by 272 packages. Updated 2020-07-06. Refresh now. Tools for package owners.