runcreator

Documentation

Overview

Package runcreator creates new Runs.

Index

• Variables
• type CL
• type Creator
  • func (rb *Creator) Create(ctx context.Context, clMutator *changelist.Mutator, pm pmNotifier, ...) (ret *run.Run, err error)
  • func (rb *Creator) ExpectedRunID() common.RunID

Variables

var StateChangedTag = errors.BoolTag{Key: errors.NewTagKey("Run Creator: state changed")}

StateChangedTag is an error tag used to indicate that state read from Datastore differs from the expected state.

Types

type CL

type CL struct {
	ID               common.CLID
	ExpectedEVersion int64
	TriggerInfo      *run.Trigger
	Snapshot         *changelist.Snapshot // Only needed for compat with CQDaemon.
}

CL is a helper struct for per-CL input for run creation.

type Creator

type Creator struct {
	// LUCIProject. Required.
	LUCIProject string
	// ConfigGroupID for the Run. Required.
	//
	// TODO(tandrii): support triggering via API calls by validating Run creation
	// request against the latest config *before* transaction.
	ConfigGroupID prjcfg.ConfigGroupID
	// InputCLs will reference the newly created Run via their IncompleteRuns
	// field, and Run's RunCL entities will reference these InputCLs back.
	// Required.
	InputCLs []CL
	// RootCL is the CL in `InputCLs` that triggers this Run in the combined mode.
	//
	// Optional.
	RootCL CL
	// Mode is the Run's mode. Required.
	Mode run.Mode
	// Definition of user defined run mode. Required if mode is not standard mode.
	ModeDefinition *cfgpb.Mode
	// Owner is the Run Owner. Required.
	Owner identity.Identity
	// BilledTo is to consume the Run quota of. Required.
	BilledTo identity.Identity
	// CreatedBy is the creator of the Run. Required.
	CreatedBy identity.Identity
	// Options is metadata of the Run. Required.
	Options *run.Options
	// ExpectedIncompleteRunIDs are a sorted slice of Run IDs which may be associated with
	// CLs.
	//
	// If CLs.IncompleteRuns reference any other Run ID, the creation will be
	// aborted and error tagged with StateChangedTag.
	//
	// Nil by default, which doesn't permit any incomplete Run.
	ExpectedIncompleteRunIDs common.RunIDs
	// OperationID is an arbitrary string uniquely identifying this creation
	// attempt. Required.
	//
	// TODO(tandrii): for CV API, record this ID in a separate entity index by
	// this ID for full idempotence of CV API.
	OperationID string
	// CreateTime is rounded by datastore.RoundTime and used as Run.CreateTime as
	// well as RunID generation.
	//
	// Optional. By default, it's the current time.
	CreateTime time.Time
	// DepRuns are the Runs that the created Run will depend on.
	DepRuns common.RunIDs
	// contains filtered or unexported fields
}

Creator creates a new Run.

If Expected<...> parameters differ from what's read from Datastore during transaction, the creation is aborted with error tagged with StateChangedTag. See Creator.Create doc.

func (*Creator) Create

func (rb *Creator) Create(ctx context.Context, clMutator *changelist.Mutator, pm pmNotifier, rm rmNotifier) (ret *run.Run, err error)

Create atomically creates a new Run.

Returns the newly created Run.

Returns 3 kinds of errors:

• tagged with transient.Tag, meaning it's reasonable to retry. Typically due to contention on simultaneously updated CL entity or transient Datastore Get/Put problem.

• tagged with StateChangedTag. This means the desired Run might still be possible to create, but it must be re-validated against updated CLs or Project config version.

• all other errors are non retryable and typically indicate a bug or severe misconfiguration. For example, lack of ProjectStateOffload entity.

func (*Creator) ExpectedRunID

func (rb *Creator) ExpectedRunID() common.RunID

ExpectedRunID returns RunID of the Run to be created.

Only works if non-Zero CreateTime is specified. Otherwise, panics.