Documentation
¶
Overview ¶
Package lease provides a way to "lock" an external resource with expiration time so that concurrent processes/task executions can achieve exclusive privilege to make mutations (generally long-running and non-idempotent) on that resource.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyOnCL ¶
func ApplyOnCL(ctx context.Context, clid common.CLID, duration time.Duration, requester string) (context.Context, func(), error)
ApplyOnCL applies for an exclusive lease on the CL.
Typically used before a Gerrit CL is mutated.
Returns:
- new time-limited context,
- best-effort lease cancellation func,
- and an error, if any.
func RetryIfLeased ¶
RetryIfLeased returns a retry.Factory that generates an iterator that retries on AlreadyInLeaseErr.
If the error != AlreadyInLease, the `next` iterator is used to compute the delays for retries.
If the error == AlreadyInLease, it tags AlreadyInLease as transient, and passes it to the `next` iterator. Then, it chooses a shorter delay between the time until lease expiry and the delay from the `next` iterator.
If the `next` delay == retry.Stop, the iterator always returns retry.Stop, whether the error was AlreadyInLease or not.
Types ¶
type AlreadyInLeaseErr ¶
type AlreadyInLeaseErr struct {
// ResourceID is the ID of the target resource.
ResourceID ResourceID
// ExpireTime is the time the current lease on the target resource expires.
ExpireTime time.Time
// Holder is the holder of the current lease on the target resource.
Holder string
}
AlreadyInLeaseErr is returned when resource is currently in lease.
func (*AlreadyInLeaseErr) Error ¶
func (e *AlreadyInLeaseErr) Error() string
Error implements `error`.
type Application ¶
type Application struct {
// ResourceID is the id of the resource that this Lease will operate on.
//
// Required and MUST be valid (See comment of `ResourceID` for format).
ResourceID ResourceID
// Holder has the privilege to mutate the resource before Lease expiration.
//
// Required.
Holder string
// Payload is used to record the mutation that the Lease holder intends to
// perform during the Lease period.
Payload []byte
// ExpireTime is the time that this Lease expires.
//
// It will be truncated to millisecond precision in the result Lease.
//
// Required, MUST be larger than the current time.
ExpireTime time.Time
}
Application contains information to apply for a Lease.
type Lease ¶
type Lease struct {
// ResourceID is the id of the resource that this lease will operate on.
ResourceID ResourceID `gae:"$id"`
// Holder has the privilege to mutate the resource before lease expiration.
Holder string `gae:",noindex"`
// Payload is used to record the mutation that the lease holder intends to
// perform during the lease period.
Payload []byte `gae:",noindex"`
// ExpireTime is the time (in ms precision) this Lease expires.
ExpireTime time.Time `gae:",noindex"`
// Token is randomly generated for each successful lease application and
// extension.
//
// It is used for fast equality check.
Token []byte `gae:",noindex"`
// contains filtered or unexported fields
}
Lease is like a mutex on external resource with expiration time.
func Apply ¶
func Apply(ctx context.Context, app Application) (*Lease, error)
Apply applies for a new lease.
Returns AlreadyInLeaseErr if the lease on this resource hasn't expired yet.
func Load ¶
func Load(ctx context.Context, rid ResourceID) (*Lease, error)
Load loads the latest Lease (may already be expired) for given resource.
Returns nil Lease if no Lease can be found for the resource.
func TryApply ¶
TryApply checks if the Lease application will go through given the latest Lease on the resource.
Returns non-nil error if the application will fail. Otherwise, returns nil error and the new Lease assuming applications succeeds.
MUST be called in a datastore transaction and the latest Lease MUST be loaded in the same transaction.
func (*Lease) Expired ¶
Expired tells whether the Lease has expired or not.
A nil Lease is always expired.
type ResourceID ¶
type ResourceID string
ResourceID is an ID identifying external resource (e.g. a Gerrit CL).
It is in the format of "type/value" where 'type' is the type of the resource and 'value' is the string id which identifies the resource.
func MakeCLResourceID ¶
func MakeCLResourceID(clid common.CLID) ResourceID
MakeCLResourceID returns ResourceID of a CL in CV.
Source Files