lease

package
v0.0.0-...-d3da680 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 4, 2024 License: Apache-2.0 Imports: 12 Imported by: 0

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

func RetryIfLeased(next retry.Factory) retry.Factory

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

func TryApply(ctx context.Context, latestLease *Lease, app Application) (*Lease, error)

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

func (l *Lease) Expired(ctx context.Context) bool

Expired tells whether the Lease has expired or not.

A nil Lease is always expired.

func (*Lease) Extend

func (l *Lease) Extend(ctx context.Context, addition time.Duration) error

Extend extends the Lease by additional duration.

Returns AlreadyInLeaseErr if this resource is not in the same lease as provided. The result expireTime will be truncated to millisecond.

func (*Lease) Terminate

func (l *Lease) Terminate(ctx context.Context) error

Terminate terminates the lease.

Returns AlreadyInLeaseErr if the provided lease doesn't currently hold the resource.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL