state

Documentation

Overview

Package state implements state machine of a Project Manager.

Index

• func SideEffectFn(s SideEffect) eventbox.SideEffectFn
• type CancelIncompleteRuns
  • func (c *CancelIncompleteRuns) Do(ctx context.Context) error
• type RunNotifier
• type SideEffect
  • func NewSideEffects(items ...SideEffect) SideEffect
• type SideEffects
  • func (s SideEffects) Do(ctx context.Context) error
• type State
  • func (s *State) ExecDeferred(ctx context.Context) (_ *State, __ SideEffect, err error)
  • func (s *State) OnCLsUpdated(ctx context.Context, clEVersions map[int64]int64) (_ *State, __ SideEffect, err error)
  • func (s *State) OnPurgesCompleted(ctx context.Context, events []*prjpb.PurgeCompleted) (_ *State, __ SideEffect, err error)
  • func (s *State) OnRunsCreated(ctx context.Context, created common.RunIDs) (_ *State, __ SideEffect, err error)
  • func (s *State) OnRunsFinished(ctx context.Context, finished common.RunIDs) (_ *State, __ SideEffect, err error)
  • func (s *State) Poke(ctx context.Context) (*State, SideEffect, error)
  • func (s *State) UpdateConfig(ctx context.Context) (*State, SideEffect, error)
  • func (s *State) UpgradeIfNecessary() *State
• type TriggerPurgeCLTasks
  • func (t *TriggerPurgeCLTasks) Do(ctx context.Context) error
• type UpdateIncompleteRunsConfig
  • func (u *UpdateIncompleteRunsConfig) Do(ctx context.Context) error

Functions

func SideEffectFn

func SideEffectFn(s SideEffect) eventbox.SideEffectFn

Types

type CancelIncompleteRuns

type CancelIncompleteRuns struct {
	RunNotifier RunNotifier
	RunIDs      common.RunIDs
}

CancelIncompleteRuns sends Cancel event to incomplete Runs.

func (*CancelIncompleteRuns) Do

func (c *CancelIncompleteRuns) Do(ctx context.Context) error

Do implements SideEffect interface.

type RunNotifier

type RunNotifier interface {
	Start(ctx context.Context, id common.RunID) error
	PokeNow(ctx context.Context, id common.RunID) error
	Cancel(ctx context.Context, id common.RunID) error
	UpdateConfig(ctx context.Context, id common.RunID, hash string, eversion int64) error
}

type SideEffect

type SideEffect interface {
	// Do is the eventbox.SideEffectFn.
	Do(context.Context) error
}

SideEffect describes action to be done transactionally with updating state in Datastore.

It may consist of several `SideEffect`s, which are executed sequentially.

Semantically, this is translatable to eventbox.SideEffectFn, but is easy to assert for in tests of this package.

func NewSideEffects

func NewSideEffects(items ...SideEffect) SideEffect

NewSideEffects returns composite SideEffect.

At least 2 items must be provided. Provided arg slice must not be mutated.

type SideEffects

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

SideEffects combines 2+ `SideEffect`s.

func (SideEffects) Do

func (s SideEffects) Do(ctx context.Context) error

Do implements SideEffect interface.

type State

type State struct {
	// PB is the serializable part of State mutated using copy-on-write approach
	// https://en.wikipedia.org/wiki/Copy-on-write
	PB *prjpb.PState

	// LogReasons is append-only accumulation of reasons to record this state for
	// posterity.
	LogReasons []prjpb.LogReason

	// Dependencies used to prepare state transitions.
	PMNotifier      *prjmanager.Notifier
	RunNotifier     RunNotifier
	CLPurger        *clpurger.Purger
	CLPoller        *poller.Poller
	ComponentTriage itriager.Triage
	// contains filtered or unexported fields
}

State is a state of Project Manager.

The state object must not be re-used except for serializing public state after its public methods returned a modified State or an error. This allows for efficient evolution of cached helper datastructures which would otherwise have to be copied, too.

To illustrate correct and incorrect usages:

s0 := &State{...}
s1, _, err := s0.Mut1()
if err != nil {
  // ... := s0.Mut2()             // NOT OK, 2nd call on s0
  return proto.Marshal(s0.PB)     // OK
}
//  ... := s0.Mut2()              // NOT OK, 2nd call on s0
s2, _, err := s1.Mut2()           // OK, s1 may be s0 if Mut1() was noop
if err != nil {
  // return proto.Marshal(s0.PB)  // OK
  return proto.Marshal(s0.PB)     // OK
}

func (*State) ExecDeferred

func (s *State) ExecDeferred(ctx context.Context) (_ *State, __ SideEffect, err error)

ExecDeferred performs previously postponed actions, notably creating Runs.

func (*State) OnCLsUpdated

func (s *State) OnCLsUpdated(ctx context.Context, clEVersions map[int64]int64) (_ *State, __ SideEffect, err error)

OnCLsUpdated updates state as a result of new changes to CLs.

clEVersions must map CL's ID to CL's EVersion. clEVersions is mutated.

func (*State) OnPurgesCompleted

func (s *State) OnPurgesCompleted(ctx context.Context, events []*prjpb.PurgeCompleted) (_ *State, __ SideEffect, err error)

OnPurgesCompleted updates state as a result of completed purge operations.

func (*State) OnRunsCreated

func (s *State) OnRunsCreated(ctx context.Context, created common.RunIDs) (_ *State, __ SideEffect, err error)

OnRunsCreated updates state after new Runs were created.

For Runs created by PM itself, this should typically be a noop, since adding newly created Run to its component should have been done right after Run creation, unless PM couldn't save its state (e.g. crashed or collided with concurrent PM invocation).

func (*State) OnRunsFinished

func (s *State) OnRunsFinished(ctx context.Context, finished common.RunIDs) (_ *State, __ SideEffect, err error)

OnRunsFinished updates state after Runs were finished.

func (*State) Poke

func (s *State) Poke(ctx context.Context) (*State, SideEffect, error)

Poke propagates "the poke" downstream to Poller & Runs.

func (*State) UpdateConfig

func (s *State) UpdateConfig(ctx context.Context) (*State, SideEffect, error)

UpdateConfig updates PM to the latest config version.

func (*State) UpgradeIfNecessary

func (s *State) UpgradeIfNecessary() *State

UpgradeIfNecessary upgrades old state to new format if necessary.

Returns the new state, or this state if nothing was changed.

type TriggerPurgeCLTasks

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

TriggerPurgeCLTasks triggers PurgeCLTasks via TQ.

func (*TriggerPurgeCLTasks) Do

func (t *TriggerPurgeCLTasks) Do(ctx context.Context) error

Do implements SideEffect interface.

type UpdateIncompleteRunsConfig

type UpdateIncompleteRunsConfig struct {
	RunNotifier RunNotifier
	RunIDs      common.RunIDs
	Hash        string
	EVersion    int64
}

UpdateIncompleteRunsConfig sends UpdateConfig events to incomplete Runs.

func (*UpdateIncompleteRunsConfig) Do

func (u *UpdateIncompleteRunsConfig) Do(ctx context.Context) error

Do implements SideEffect interface.