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 Handler
  • func (h *Handler) ExecDeferred(ctx context.Context, s *State) (_ *State, __ SideEffect, err error)
  • func (h *Handler) OnCLsUpdated(ctx context.Context, s *State, clEVersions map[int64]int64) (_ *State, __ SideEffect, err error)
  • func (h *Handler) OnPurgesCompleted(ctx context.Context, s *State, events []*prjpb.PurgeCompleted) (_ *State, __ SideEffect, evsToConsume []int, err error)
  • func (h *Handler) OnRunsCreated(ctx context.Context, s *State, created common.RunIDs) (_ *State, __ SideEffect, err error)
  • func (h *Handler) OnRunsFinished(ctx context.Context, s *State, finished map[common.RunID]run.Status) (_ *State, __ SideEffect, err error)
  • func (h *Handler) OnTriggeringCLDepsCompleted(ctx context.Context, s *State, events []*prjpb.TriggeringCLDepsCompleted) (_ *State, __ SideEffect, evIndexesToConsume []int, err error)
  • func (h *Handler) Poke(ctx context.Context, s *State) (*State, SideEffect, error)
  • func (h *Handler) UpdateConfig(ctx context.Context, s *State) (*State, SideEffect, error)
• type RunNotifier
• type ScheduleTriggeringCLDepsTasks
  • func (t *ScheduleTriggeringCLDepsTasks) Do(ctx context.Context) error
• type SideEffect
  • func NewSideEffects(items ...SideEffect) SideEffect
• type SideEffects
  • func (s SideEffects) Do(ctx context.Context) error
• type State
  • 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 Handler

type Handler struct {
	CLMutator       *changelist.Mutator
	PMNotifier      *prjmanager.Notifier
	RunNotifier     RunNotifier
	CLPurger        *clpurger.Purger
	CLTriggerer     *cltriggerer.Triggerer
	CLPoller        *poller.Poller
	ComponentTriage itriager.Triage
}

Handler handles state transitions of a project.

func (*Handler) ExecDeferred

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

ExecDeferred performs previously postponed actions, notably creating Runs.

func (*Handler) OnCLsUpdated

func (h *Handler) OnCLsUpdated(ctx context.Context, s *State, 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 (*Handler) OnPurgesCompleted

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

OnPurgesCompleted updates state as a result of completed purge operations.

func (*Handler) OnRunsCreated

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

OnRunsCreated updates state after new Runs were created.

func (*Handler) OnRunsFinished

func (h *Handler) OnRunsFinished(ctx context.Context, s *State, finished map[common.RunID]run.Status) (_ *State, __ SideEffect, err error)

OnRunsFinished updates state after Runs were finished.

func (*Handler) OnTriggeringCLDepsCompleted

func (h *Handler) OnTriggeringCLDepsCompleted(ctx context.Context, s *State, events []*prjpb.TriggeringCLDepsCompleted) (_ *State, __ SideEffect, evIndexesToConsume []int, err error)

OnTriggeringCLDepsCompleted manages TriggeringCLDeps completion events.

func (*Handler) Poke

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

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

func (*Handler) UpdateConfig

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

UpdateConfig updates PM to the latest config version.

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, reason string) error
	UpdateConfig(ctx context.Context, id common.RunID, hash string, eversion int64) error
}

type ScheduleTriggeringCLDepsTasks

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

ScheduleTriggeringCLDepsTasks schedules TriggeringCLDepsTask(s) via TQ.

func (*ScheduleTriggeringCLDepsTasks) Do

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

Do implements SideEffect interface.

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
	// 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) 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.