longrunning

README

longrunning

A helper library for working with long running operations.

Install

go get cloud.google.com/go/longrunning

Go Version Support

See the Go Versions Supported section in the root directory's README.

Contributing

Contributions are welcome. Please, see the CONTRIBUTING document for details.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Contributor Code of Conduct for more information.

Documentation

Overview

Package longrunning supports Long Running Operations for the Google Cloud Libraries. See google.golang.org/genproto/googleapis/longrunning for its service definition.

Users of the Google Cloud Libraries will typically not use this package directly. Instead they will call functions returning Operations and call their methods.

This package is still experimental and subject to change.

Index

• Constants
• Variables
• type Operation
  • func InternalNewOperation(inner *autogen.OperationsClient, proto *pb.Operation) *Operation
  • func (op *Operation) Cancel(ctx context.Context, opts ...gax.CallOption) error
  • func (op *Operation) Delete(ctx context.Context, opts ...gax.CallOption) error
  • func (op *Operation) Done() bool
  • func (op *Operation) Metadata(meta protoadapt.MessageV1) error
  • func (op *Operation) Name() string
  • func (op *Operation) Poll(ctx context.Context, resp protoadapt.MessageV1, opts ...gax.CallOption) error
  • func (op *Operation) Wait(ctx context.Context, resp protoadapt.MessageV1, opts ...gax.CallOption) error
  • func (op *Operation) WaitWithInterval(ctx context.Context, resp protoadapt.MessageV1, interval time.Duration, ...) error

Examples

• Operation.Cancel
• Operation.Delete
• Operation.Metadata
• Operation.Wait

Constants

const DefaultWaitInterval = 60 * time.Second

DefaultWaitInterval is the polling interval used by Operation.Wait.

Variables

var ErrNoMetadata = errors.New("operation contains no metadata")

ErrNoMetadata is the error returned by Metadata if the operation contains no metadata.

Types

type Operation

type Operation struct {
	// contains filtered or unexported fields
}

Operation represents the result of an API call that may not be ready yet.

func InternalNewOperation

func InternalNewOperation(inner *autogen.OperationsClient, proto *pb.Operation) *Operation

InternalNewOperation is for use by the google Cloud Libraries only.

InternalNewOperation returns an long-running operation, abstracting the raw pb.Operation. The conn parameter refers to a server that proto was received from.

func (*Operation) Cancel

func (op *Operation) Cancel(ctx context.Context, opts ...gax.CallOption) error

Cancel starts asynchronous cancellation on a long-running operation. The server makes a best effort to cancel the operation, but success is not guaranteed. If the server doesn't support this method, it returns status.Code(err) == codes.Unimplemented. Clients can use Poll or other methods to check whether the cancellation succeeded or whether the operation completed despite cancellation. On successful cancellation, the operation is not deleted; instead, op.Poll returns an error with code Canceled.

Example

op, err := bestMomentInHistory()
if err != nil {
	// TODO: Handle err.
}
if err := op.Cancel(context.Background()); err != nil {
	// TODO: Handle err.
}

func (*Operation) Delete

func (op *Operation) Delete(ctx context.Context, opts ...gax.CallOption) error

Delete deletes a long-running operation. This method indicates that the client is no longer interested in the operation result. It does not cancel the operation. If the server doesn't support this method, status.Code(err) == codes.Unimplemented.

Example

op, err := bestMomentInHistory()
if err != nil {
	// TODO: Handle err.
}
if err := op.Delete(context.Background()); err != nil {
	// TODO: Handle err.
}

func (*Operation) Done

func (op *Operation) Done() bool

Done reports whether the long-running operation has completed.

func (*Operation) Metadata

func (op *Operation) Metadata(meta protoadapt.MessageV1) error

Metadata unmarshals op's metadata into meta. If op does not contain any metadata, Metadata returns ErrNoMetadata and meta is unmodified.

Example

op, err := bestMomentInHistory()
if err != nil {
	// TODO: Handle err.
}

// The operation might contain metadata.
// In this example, the metadata contains the estimated length of time
// the operation might take to complete.
var meta durationpb.Duration
if err := op.Metadata(&meta); err != nil {
	// TODO: Handle err.
}
if err := meta.CheckValid(); err == ErrNoMetadata {
	fmt.Println("no metadata")
	return
} else if err != nil {
	// TODO: Handle err.
	return
}
fmt.Println(meta.AsDuration())

Output:

1h0m0s

func (*Operation) Name

func (op *Operation) Name() string

Name returns the name of the long-running operation. The name is assigned by the server and is unique within the service from which the operation is created.

func (*Operation) Poll

func (op *Operation) Poll(ctx context.Context, resp protoadapt.MessageV1, opts ...gax.CallOption) error

Poll fetches the latest state of a long-running operation.

If Poll fails, the error is returned and op is unmodified. If Poll succeeds and the operation has completed with failure, the error is returned and op.Done will return true. If Poll succeeds and the operation has completed successfully, op.Done will return true; if resp != nil, the response of the operation is stored in resp.

func (*Operation) Wait

func (op *Operation) Wait(ctx context.Context, resp protoadapt.MessageV1, opts ...gax.CallOption) error

Wait is equivalent to WaitWithInterval using DefaultWaitInterval.

Example

// Complex computation, might take a long time.
op, err := bestMomentInHistory()
if err != nil {
	// TODO: Handle err.
}
var ts timestamppb.Timestamp
err = op.Wait(context.TODO(), &ts)
if err != nil && !op.Done() {
	fmt.Println("failed to fetch operation status", err)
} else if err != nil && op.Done() {
	fmt.Println("operation completed with error", err)
} else {
	fmt.Println(ts.AsTime().Format(time.RFC3339Nano))
}

Output:

2009-11-10T23:00:00Z

func (*Operation) WaitWithInterval

func (op *Operation) WaitWithInterval(ctx context.Context, resp protoadapt.MessageV1, interval time.Duration, opts ...gax.CallOption) error

WaitWithInterval blocks until the operation is completed. If resp != nil, Wait stores the response in resp. WaitWithInterval polls every interval, except initially when it polls using exponential backoff.

See documentation of Poll for error-handling information.