juju: github.com/juju/juju/core/lease Index | Files

package lease

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

Index

Package Files

interface.go store.go

Constants

const (
    // ApplicationLeadershipNamespace is the namespace used to manage
    // leadership leases.
    ApplicationLeadershipNamespace = "application-leadership"

    // SingularControllerNamespace is the namespace used to manage
    // controller leases.
    SingularControllerNamespace = "singular-controller"
)

Variables

var (
    // ErrInvalid indicates that a Store operation failed because latest state
    // indicates that it's a logical impossibility. It's a short-range signal to
    // calling code only; that code should never pass it on, but should inspect
    // the Store's updated Leases() and either attempt a new operation or return
    // a new error at a suitable level of abstraction.
    ErrInvalid = errors.New("invalid lease operation")

    // ErrTimeout indicates that a Store operation failed because it
    // couldn't update the underlying lease information. This is probably
    // a transient error due to changes in the cluster, and indicates that
    // the operation should be retried.
    ErrTimeout = errors.New("lease operation timed out")

    // ErrAborted indicates that the stop channel returned before the operation
    // succeeded or failed.
    ErrAborted = errors.New("lease operation aborted")
)
var ErrClaimDenied = errors.New("lease claim denied")

ErrClaimDenied indicates that a Claimer.Claim() has been denied.

var ErrNotHeld = errors.New("lease not held")

ErrNotHeld indicates that some holder does not hold some lease.

var ErrWaitCancelled = errors.New("waiting for lease cancelled by client")

ErrWaitCancelled is returned by Claimer.WaitUntilExpired if the cancel channel is closed.

func IsAborted Uses

func IsAborted(err error) bool

IsAborted returns whether the specified error represents ErrAborted (even if it's wrapped).

func IsInvalid Uses

func IsInvalid(err error) bool

IsInvalid returns whether the specified error represents ErrInvalid (even if it's wrapped).

func IsTimeout Uses

func IsTimeout(err error) bool

IsTimeout returns whether the specified error represents ErrTimeout (even if it's wrapped).

func LockedTrapdoor Uses

func LockedTrapdoor(attempt int, key interface{}) error

LockedTrapdoor is a Trapdoor suitable for use by substrates that don't want or need to expose their internals.

func ValidateString Uses

func ValidateString(s string) error

ValidateString returns an error if the string is empty, or if it contains whitespace, or if it contains any character in `.#$`. Store implementations are expected to always reject invalid strings, and never to produce them.

type Checker Uses

type Checker interface {

    // Token returns a Token that can be interrogated at any time to discover
    // whether the supplied lease is currently held by the supplied holder.
    Token(leaseName, holderName string) Token
}

Checker exposes facts about lease ownership.

type Claimer Uses

type Claimer interface {

    // Claim acquires or extends the named lease for the named holder. If it
    // succeeds, the holder is guaranteed to keep the lease until at least
    // duration after the *start* of the call. If it returns ErrClaimDenied,
    // the holder is guaranteed not to have the lease. If it returns any other
    // error, no reasonable inferences may be made.
    Claim(leaseName, holderName string, duration time.Duration) error

    // WaitUntilExpired returns nil when the named lease is no longer held. If it
    // returns any error, no reasonable inferences may be made. If the supplied
    // cancel channel is non-nil, it can be used to cancel the request; in this
    // case, the method will return ErrWaitCancelled.
    WaitUntilExpired(leaseName string, cancel <-chan struct{}) error
}

Claimer exposes lease acquisition and expiry notification capabilities.

type Info Uses

type Info struct {

    // Holder is the name of the current leaseholder.
    Holder string

    // Expiry is the latest time at which it's possible the lease might still
    // be valid. Attempting to expire the lease before this time will fail.
    Expiry time.Time

    // Trapdoor exposes the originating Store's persistence substrate, if the
    // substrate exposes any such capability. It's useful specifically for
    // integrating mgo/txn-based components: which thus get a mechanism for
    // extracting assertion operations they can use to gate other substrate
    // changes on lease state.
    Trapdoor Trapdoor
}

Info holds substrate-independent information about a lease; and a substrate- specific trapdoor func.

type Key Uses

type Key struct {
    Namespace string
    ModelUUID string
    Lease     string
}

Key fully identifies a lease, including the namespace and model it belongs to.

type Manager Uses

type Manager interface {
    Checker(namespace string, modelUUID string) (Checker, error)
    Claimer(namespace string, modelUUID string) (Claimer, error)
    Pinner(namespace string, modelUUID string) (Pinner, error)
    Reader(namespace string, modelUUID string) (Reader, error)
}

Manager describes methods for acquiring objects that manipulate and query leases for different models.

type Pinner Uses

type Pinner interface {

    // Pin ensures that the current holder of input lease name will not lose
    // the lease to expiry.
    // If there is no current holder of the lease, the next claimant will be
    // the recipient of the pin behaviour.
    // The input entity denotes the party responsible for the
    // pinning operation.
    Pin(leaseName string, entity string) error

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

    // Pinned returns all names for pinned leases, with the entities requiring
    // their pinned behaviour.
    Pinned() map[string][]string
}

Pinner describes methods used to manage suspension of lease expiry.

type Reader Uses

type Reader interface {
    Leases() map[string]string
}

Reader describes retrieval of all leases and holders for a known namespace and model.

type Request Uses

type Request struct {

    // Holder identifies the lease holder.
    Holder string

    // Duration specifies the time for which the lease is required.
    Duration time.Duration
}

Request describes a lease request.

func (Request) Validate Uses

func (request Request) Validate() error

Validate returns an error if any fields are invalid or inconsistent.

type Store Uses

type Store interface {

    // ClaimLease records the supplied holder's claim to the supplied lease. If
    // it succeeds, the claim is guaranteed until at least the supplied duration
    // after the call to ClaimLease was initiated. If it returns ErrInvalid,
    // check Leases() for updated state.
    ClaimLease(lease Key, request Request, stop <-chan struct{}) error

    // ExtendLease records the supplied holder's continued claim to the supplied
    // lease, if necessary. If it succeeds, the claim is guaranteed until at
    // least the supplied duration after the call to ExtendLease was initiated.
    // If it returns ErrInvalid, check Leases() for updated state.
    ExtendLease(lease Key, request Request, stop <-chan struct{}) error

    // ExpireLease records the vacation of the supplied lease. It will fail if
    // we cannot verify that the lease's writer considers the expiry time to
    // have passed. If it returns ErrInvalid, check Leases() for updated state.
    ExpireLease(lease Key) error

    // Leases returns a recent snapshot of lease state. Expiry times are
    // expressed according to the Clock the store was configured with.
    // Supplying any lease keys will filter the return for those requested.
    Leases(keys ...Key) map[Key]Info

    // LeaseGroup returns a snapshot of all of the leases for a
    // particular namespace/model combination. This is useful for
    // reporting holder information for a model, and can often be
    // implemented more efficiently than getting all leases when there
    // are many models.
    LeaseGroup(namespace, modelUUID string) map[Key]Info

    // Refresh reads all lease state from the database.
    Refresh() error

    // Pin ensures that the current holder of the lease for the input key will
    // not lose the lease to expiry.
    // If there is no current holder of the lease, the next claimant will be
    // the recipient of the pin behaviour.
    // The input entity denotes the party responsible for the
    // pinning operation.
    PinLease(lease Key, entity string, stop <-chan struct{}) error

    // Unpin reverses a Pin operation for the same key and entity.
    // Normal expiry behaviour is restored when no entities remain with
    // pins for the application.
    UnpinLease(lease Key, entity string, stop <-chan struct{}) error

    // Pinned returns a snapshot of pinned leases.
    // The return consists of each pinned lease and the collection of entities
    // requiring its pinned behaviour.
    Pinned() map[Key][]string

    // Autoexpire indicates whether this store expires leases
    // automatically as time is updated, or whether the client code
    // needs to remove expired leases.
    Autoexpire() bool
}

Store manipulates leases directly, and is most likely to be seen set on a worker/lease.ManagerConfig struct (and used by the Manager). Implementations of Store are not expected to be goroutine-safe.

type Token Uses

type Token interface {

    // Check returns ErrNotHeld if the lease it represents is not held
    // by the holder it represents. If attempt is 0, trapdoorKey is
    // nil, and Check returns nil, then the token continues to
    // represent a true fact.
    //
    // Attempt is the number of times this check has been tried (not
    // necessarily with this token instance). This enables an
    // implementation to vary how it deals with trapdoorKey across
    // attempts. For example, the raft implementation generates
    // different ops for the first attempt than for subsequent
    // attempts.
    //
    // If the token represents a true fact and trapdoorKey is *not*
    // nil, it will be passed through layers for the attention of the
    // underlying lease.Client implementation. If you need to do this,
    // consult the documentation for the particular Client you're
    // using to determine what key should be passed and what errors
    // that might induce.
    Check(attempt int, trapdoorKey interface{}) error
}

Token represents a fact -- but not necessarily a *true* fact -- about some holder's ownership of some lease.

type Trapdoor Uses

type Trapdoor func(attempt int, key interface{}) error

Trapdoor allows a store to use pre-agreed special knowledge to communicate with a Store substrate by passing a key with suitable properties.

Package lease imports 3 packages (graph) and is imported by 194 packages. Updated 2019-06-23. Refresh now. Tools for package owners.