Documentation
¶
Overview ¶
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.
Index ¶
Constants ¶
This section is empty.
Variables ¶
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.
Functions ¶
func IsNotLeaderError ¶
IsNotLeaderError returns whether this error represents a token check that failed because the unit in question wasn't the leader.
func NewNotLeaderError ¶
NewNotLeaderError returns an error indicating that this unit is not the leader of that application.
Types ¶
type Checker ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
type TrackerWorker interface {
worker.Worker
Tracker
}
TrackerWorker represents a leadership tracker worker.
Source Files
Directories