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.