Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrClaimDenied = errors.New("lease claim denied")
ErrClaimDenied indicates that a Claimer.Claim() has been denied.
var ErrInvalid = errors.New("invalid lease operation")
ErrInvalid indicates that a Client 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 Client's updated Leases() and either attempt a new operation or return a new error at a suitable level of abstraction.
var ErrNotHeld = errors.New("lease not held")
ErrNotHeld indicates that some holder does not hold some lease.
Functions ¶
func LockedTrapdoor ¶
func LockedTrapdoor(key interface{}) error
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 `.#$`. Client 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 other error, no reasonable inferences may be made.
WaitUntilExpired(leaseName string) error
}
Claimer exposes lease acquisition and expiry notification capabilities.
type Client ¶
type Client 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 string, request Request) 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 string, request Request) 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 string) error
// Leases returns a recent snapshot of lease state. Expiry times are
// expressed according to the Clock the client was configured with.
Leases() map[string]Info
// Refresh reads all lease state from the database.
Refresh() error
}
Client manipulates leases directly, and is most likely to be seen set on a worker/lease.ManagerConfig struct (and used by the Manager). Implementations of Client are not expected to be goroutine-safe.
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 Client'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 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 Token ¶
type Token interface {
// Check returns ErrNotHeld if the lease it represents is not held by the
// holder it represents. If trapdoorKey is nil, and Check returns nil, then
// the token continues to represent a true fact.
//
// 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(trapdoorKey interface{}) error
}
Token represents a fact -- but not necessarily a *true* fact -- about some holder's ownership of some lease.
Source Files