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

    View Source
    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.

      Functions

      This section is empty.

      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.

                          Source Files