lease

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

• Variables
• type Application
• type Lease
  • func Apply(ctx context.Context, app Application) (*Lease, error)
  • func Load(ctx context.Context, rid ResourceID) (*Lease, error)
  • func TryApply(ctx context.Context, latestLease *Lease, app Application) (*Lease, error)
  • func (l *Lease) Expired(ctx context.Context) bool
  • func (l *Lease) Extend(ctx context.Context, addition time.Duration) error
  • func (l *Lease) Terminate(ctx context.Context) error
• type ResourceID
  • func MakeCLResourceID(clid common.CLID) ResourceID

Variables

var ErrConflict = errors.New("Resource is currently in lease")

ErrConflict is returned when resource is currently in lease so that operations like `Apply`, `Extend` can't proceed.

Types

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 ErrConflict if the resource is already in lease.

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 ErrConflict if the Lease is not current for the resource. The result expireTime will be truncated to millisecond.

func (*Lease) Terminate

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

Terminate terminates the lease.

Returns ErrConflict if the lease is not current for 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.