Documentation
¶
Index ¶
- Constants
- Variables
- func IsAborted(err error) bool
- func IsDeadlineExceeded(err error) bool
- func IsDropped(err error) bool
- func IsHeld(err error) bool
- func IsInvalid(err error) bool
- func IsLeaseError(err error) bool
- func IsNotHeld(err error) bool
- func IsTimeout(err error) bool
- func LockedTrapdoor(attempt int, key interface{}) error
- func ValidateString(s string) error
- type Checker
- type Claimer
- type Info
- type Key
- type Manager
- type Pinner
- type Reader
- type Request
- type Revoker
- type Store
- type Token
- type Trapdoor
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 ( // ErrClaimDenied indicates that a Claimer.Claim() has been denied. ErrClaimDenied = errors.New("lease claim denied") // ErrNotHeld indicates that some holder does not hold some lease. ErrNotHeld = errors.New("lease not held") // ErrWaitCancelled is returned by Claimer.WaitUntilExpired if the // cancel channel is closed. ErrWaitCancelled = errors.New("waiting for lease cancelled by client") // 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") // ErrHeld indicates that a claim operation was impossible to fulfill // because the lease has been claimed on behalf of another entity. // This operation should not be retried. ErrHeld = errors.New("lease already held") // 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") // ErrDropped indicated that the underlying request was dropped. This is // indicative of no valid connection to propagate the lease operation to // the leader. ErrDropped = errors.New("lease operation dropped") // ErrDeadlineExceeded indicates if the underlying request was rejected // because enqueuing exceeded the timeout. ErrDeadlineExceeded = errors.New("lease deadline exceeded") )
Functions ¶
func IsAborted ¶
IsAborted returns whether the specified error represents ErrAborted (even if it's wrapped).
func IsDeadlineExceeded ¶
IsDeadlineExceeded returns whether the specified errors represents ErrDeadlineExceeded (even if it's wrapped).
func IsDropped ¶
IsDropped returns whether the specified error represents ErrErrDropped (even if it's wrapped).
func IsInvalid ¶
IsInvalid returns whether the specified error represents ErrInvalid (even if it's wrapped).
func IsLeaseError ¶
IsLeaseError returns whether the specified error is part of the collection of lease errors.
func IsNotHeld ¶
IsNotHeld returns whether the specified error represents ErrNotHeld (even if it's wrapped).
func IsTimeout ¶
IsTimeout returns whether the specified error represents ErrTimeout (even if it's wrapped).
func LockedTrapdoor ¶
LockedTrapdoor is a Trapdoor suitable for use by substrates that don't want or need to expose their internals.
func ValidateString ¶
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.
Types ¶
type Checker ¶
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 ¶
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 ¶
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 Manager ¶
type Manager interface {
Checker(namespace string, modelUUID string) (Checker, error)
Claimer(namespace string, modelUUID string) (Claimer, error)
Revoker(namespace string, modelUUID string) (Revoker, 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 ¶
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 Request ¶
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.
type Revoker ¶
type Revoker interface {
// Revoke releases the named lease for the named holder.
Revoke(leaseName, holderName string) error
}
Revoker exposes lease revocation capabilities.
type Store ¶
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
// RevokeLease records the vacation of the supplied lease. It will fail if
// the lease is not held by the holder.
RevokeLease(lease Key, holder string, stop <-chan struct{}) 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
// PinLease 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
// UnpinLease 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
}
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 ¶
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.