Source File
	transition.go

Belonging Package
	/pkg/machine

package machine

import (
	"fmt"
	"maps"
	"slices"
	"strings"
	"sync"
	"sync/atomic"
)

// Transition represents processing of a single mutation within a machine.
type Transition struct {
	// Id is a unique identifier of the transition.
	Id string
	// Steps is a list of steps taken by this transition (so far).
	Steps []*Step
	// HasStateChanged is true if the transition has changed the state of the
	// machine. TODO useful?
	// HasStateChanged bool
	// TimeBefore is the machine time from before the transition.
	TimeBefore Time
	// TimeAfter is the machine time from after the transition. If the transition
	// has been canceled, this will be the same as TimeBefore. This field is the
	// same as TimeBefore, until the negotiation phase finishes.
	TimeAfter Time
	// TargetIndexes is a list of indexes of the target states.
	TargetIndexes []int
	// Enters is a list of states activated in this transition.
	Enters S
	// Enters is a list of states deactivated in this transition.
	Exits S
	// Mutation call which caused this transition
	Mutation *Mutation
	// Machine is the parent machine of this transition.
	Machine *Machine
	// MachApi is a subset of Machine.
	// TODO call when applicable instead of calling Machine
	// TODO rename to MachApi
	MachApi Api
	// LogEntries are log msgs produced during the transition.
	LogEntries []*LogEntry
	// PreLogEntries are log msgs produced before during the transition.
	PreLogEntries []*LogEntry
	// QueueLen is the length of the queue after the transition.
	QueueLen uint16
	// InternalLogEntriesLock is used to lock the logs to be collected by Tracers.
	// TODO getter?
	InternalLogEntriesLock sync.Mutex
	// IsCompleted returns true when the execution of the transition has been
	// fully completed.
	IsCompleted atomic.Bool
	// IsAccepted returns true if the transition has been accepted, which can
	// change during the transition's negotiation phase and while resolving
	// relations.
	IsAccepted atomic.Bool
	// TODO true for panic and timeouts
	IsBroken atomic.Bool
	// TODO confirms relations resolved and negotiation ended
	IsSettled atomic.Bool

	// last step info for panic recovery
	latestHandlerIsEnter bool
	latestHandlerIsFinal bool
	latestHandlerToState string

	cacheTargetStates atomic.Pointer[S]
	cacheStatesBefore atomic.Pointer[S]
	cacheClockBefore  atomic.Pointer[Clock]
	cacheActivated    S
	cacheDeactivated  S
	cacheSchema       Schema
}

// newTransition creates a new transition for the given mutation.
func newTransition(m *Machine, mut *Mutation) *Transition {
	m.activeStatesMx.RLock()
	defer m.activeStatesMx.RUnlock()

	index := m.StateNames()
	schema := m.Schema()
	tNow := m.time(nil)
	tAfter := slices.Clone(tNow)
	semlog := m.SemLogger()

	// gather what we know about TimeAfter at this point (except for checks)
	// TODO test case
	if !mut.IsCheck {
		is := IsActiveTick
		for _, idx := range mut.Called {
			name := index[idx]
			switch {
			case mut.Type == MutationAdd && is(tAfter[idx]) && schema[name].Multi:
				tAfter[idx] += 2
			case mut.Type == MutationAdd && !is(tAfter[idx]):
				tAfter[idx] += 1
			case mut.Type == MutationRemove && is(tAfter[idx]):
				tAfter[idx] += 1
			}
			// TODO support [MutationSet]
		}
	}

	t := &Transition{
		Id:          randId(),
		Mutation:    mut,
		TimeBefore:  tNow,
		TimeAfter:   tAfter,
		Machine:     m,
		MachApi:     m,
		cacheSchema: schema,
	}

	activeStates := slices.Clone(m.activeStates)
	t.cacheStatesBefore.Store(&activeStates)
	clock := maps.Clone(m.clock)
	t.cacheClockBefore.Store(&clock)
	t.IsAccepted.Store(true)

	// assign early to catch the logs
	m.t.Store(t)

	// tracers
	m.tracersMx.RLock()
	for _, tracer := range m.tracers {
		if t.Machine.IsDisposed() {
			break
		}
		tracer.TransitionInit(t)
	}
	m.tracersMx.RUnlock()

	// log stuff
	called := t.CalledStates()
	mutType := t.Type()
	logArgs := ""
	if semlog.IsArgs() || semlog.Level() > LogExternal {
		logArgs = mut.LogArgs(semlog.ArgsMapper())
	}
	if t.isLogSteps() {
		t.addSteps(newSteps("", called, StepRequested, 0)...)
	}
	if mut.IsAuto {
		m.log(LogDecisions, "[%s:auto] %s%s", mutType, j(called), logArgs)
	} else {
		m.log(LogOps, "[%s] %s%s", mutType, j(called), logArgs)
	}
	src := mut.Source
	if src != nil {
		m.log(LogOps, "[source] %s/%s/%d", src.MachId, src.TxId, src.MachTime)
	}

	// set up the mutation
	statesToSet := t.statesToSet(mutType, called)
	targetStates := m.resolver.TargetStates(t, statesToSet, index)

	// simulate TimeAfter (temporarily)
	t.TargetIndexes = m.Index(targetStates)
	t.cacheTargetStates.Store(&targetStates)

	impliedStates := StatesDiff(targetStates, statesToSet)
	if len(impliedStates) > 0 {
		m.log(LogOps, "[implied] %s", j(impliedStates))
	}

	t.setupAccepted()
	if t.IsAccepted.Load() {
		t.setupExitEnter()
	}

	return t
}

func (t *Transition) statesToSet(mutType MutationType, states S) S {
	m := t.Machine

	switch mutType {

	case MutationRemove:
		statesToSet := slicesFilter(m.activeStates, func(state string, _ int) bool {
			return !slices.Contains(states, state)
		})
		if t.isLogSteps() {
			t.addSteps(newSteps("", states, StepRemove, 0)...)
		}

		return statesToSet

	case MutationAdd:
		statesToSet := slices.Concat(states, m.activeStates)
		if t.isLogSteps() {
			t.addSteps(newSteps("", StatesDiff(statesToSet, m.activeStates),
				StepSet, 0)...)
		}

		return statesToSet

	case MutationSet:
		statesToSet := states
		if t.isLogSteps() {
			t.addSteps(newSteps("", StatesDiff(statesToSet, m.activeStates),
				StepSet, 0)...)
			t.addSteps(newSteps("", StatesDiff(m.activeStates, statesToSet),
				StepRemove, 0)...)
		}

		return statesToSet
	}

	return nil
}

func (t *Transition) CleanCache() {
	t.cacheTargetStates.Store(nil)
	t.cacheStatesBefore.Store(nil)
	t.latestHandlerToState = ""
	t.latestHandlerIsEnter = false
	t.latestHandlerIsFinal = false
	t.cacheClockBefore.Store(nil)
	t.Mutation.cacheCalled.Store(nil)
	t.cacheSchema = nil
}

// StatesBefore is a list of states before the transition.
func (t *Transition) StatesBefore() S {
	// cache
	if v := t.cacheStatesBefore.Load(); v != nil {
		return *v
	}

	// TODO should preserve order?
	ret := make(S, 0, len(t.TimeBefore))
	mach := t.Machine
	if mach == nil {
		return ret
	}
	states := mach.StateNames()
	for i := range t.TimeBefore {
		if IsActiveTick(t.TimeBefore[i]) {
			ret = append(ret, states[i])
		}
	}

	return ret
}

// TargetStates is a list of states after parsing the relations.
func (t *Transition) TargetStates() S {
	// cache
	if v := t.cacheTargetStates.Load(); v != nil {
		return *v
	}

	ret := make(S, len(t.TargetIndexes))
	mach := t.MachApi
	if mach == nil {
		return nil
	}
	states := mach.StateNames()
	for i, idx := range t.TargetIndexes {
		if idx == -1 {
			// disposed
			return S{}
		}
		ret[i] = states[idx]
	}

	return ret
}

// IsAuto returns true if the transition was triggered by an auto state.
// Thus, it cant trigger any other auto state mutations.
func (t *Transition) IsAuto() bool {
	return t.Mutation.IsAuto
}

// IsHealth returns true if the transition was health-related (StateHealthcheck,
// StateHeartbeat).
func (t *Transition) IsHealth() bool {
	c := t.CalledStates()

	if len(c) != 1 || t.Type() != MutationAdd {
		return false
	}

	return c[0] == StateHealthcheck || c[0] == StateHeartbeat
}

// CalledStates return explicitly called / requested states of the transition.
func (t *Transition) CalledStates() S {
	// cache
	if v := t.Mutation.cacheCalled.Load(); v != nil {
		return *v
	}

	return IndexToStates(t.MachApi.StateNames(), t.Mutation.Called)
}

// TimeIndexAfter return TimeAfter bound to an index, for easy quering.
func (t *Transition) TimeIndexAfter() TimeIndex {
	return TimeIndex{
		Time:  t.TimeAfter,
		Index: t.MachApi.StateNames(),
	}
}

// ClockBefore return the Clock from before the transition.
func (t *Transition) ClockBefore() Clock {
	// cache
	if v := t.cacheClockBefore.Load(); v != nil {
		return *v
	}

	states := t.Machine.StateNames()
	ret := make(Clock, len(states))
	for k, v := range t.TimeBefore {
		ret[states[k]] = v
	}

	return ret
}

// ClockAfter return the Clock from before the transition.
func (t *Transition) ClockAfter() Clock {
	states := t.Machine.StateNames()
	ret := make(Clock, len(states))
	for k, v := range t.TimeAfter {
		ret[states[k]] = v
	}

	return ret
}

// Args returns the argument map passed to the mutation method
// (or an empty one).
func (t *Transition) Args() A {
	return t.Mutation.Args
}

// Type returns the type of the mutation (add, remove, set).
func (t *Transition) Type() MutationType {
	return t.Mutation.Type
}

// String representation of the transition and the steps taken so far.
func (t *Transition) String() string {
	index := t.Machine.StateNames()
	var lines []string
	for _, step := range t.Steps {
		lines = append(lines, step.StringFromIndex(index))
	}

	steps := strings.Join(lines, "\n- ")
	if steps != "" {
		steps = "\n- " + steps
	}

	source := ""
	mutSrc := t.Mutation.Source
	if mutSrc != nil {
		source = fmt.Sprintf("\nsource: [%s](%s/%s/t%d)", mutSrc.TxId,
			mutSrc.MachId, mutSrc.TxId, mutSrc.MachTime)
	}

	return fmt.Sprintf("tx#%s\n%s%s%s", t.Id, t.Mutation.StringFromIndex(index),
		source, steps)
}

func (t *Transition) addSteps(steps ...*Step) {
	t.Steps = append(t.Steps, steps...)
}

func (t *Transition) setupExitEnter() {
	m := t.Machine

	// collect the exit handlers
	targetStates := t.TargetStates()
	exits := StatesDiff(m.activeStates, targetStates)
	m.resolver.SortStates(exits)

	// collect the enters handlers
	var enters S
	for _, s := range targetStates {
		// enter activate state only for multi states called directly
		state := m.schema[s]
		if !m.is(S{s}) || (state.Multi && slices.Contains(t.CalledStates(), s)) {
			enters = append(enters, s)
		}
	}

	// save
	t.Exits = exits
	t.Enters = enters
}

func (t *Transition) emitSelfEvents() Result {
	m := t.Machine
	ret := Executed
	var handlerCalled bool
	for _, s := range t.CalledStates() {
		// only the active states
		if !t.Machine.Is(S{s}) {
			continue
		}

		name := s + s
		t.latestHandlerToState = s
		ret, handlerCalled = m.handle(name, t.Mutation.Args, false, false, true)
		if handlerCalled && t.isLogSteps() {
			step := newStep("", s, StepHandler, 0)
			step.IsSelf = true
			t.addSteps(step)
		}
		if ret == Canceled {
			break
		}
	}

	return ret
}

func (t *Transition) emitEnterEvents() Result {
	for _, toState := range t.Enters {
		args := t.Mutation.Args

		// FooEnter
		ret := t.emitHandler("", toState, false, true, toState+SuffixEnter, args)
		if ret == Canceled {
			if t.IsAuto() {
				// partial auto state acceptance
				targetStates := t.TargetStates()
				idx := slices.Index(targetStates, toState)
				t.TargetIndexes = slices.Delete(t.TargetIndexes, idx, idx+1)
				targetStates = slices.Delete(targetStates, idx, idx+1)
				t.cacheTargetStates.Store(&targetStates)
			} else {
				return ret
			}
		}
	}

	return Executed
}

func (t *Transition) emitExitEvents() Result {
	for _, fromState := range t.Exits {
		// FooExit
		ret := t.emitHandler(fromState, "", false, false, fromState+SuffixExit,
			t.Mutation.Args)
		if ret == Canceled {
			if t.IsAuto() {
				// partial auto state acceptance
				targetStates := t.TargetStates()
				idx := slices.Index(targetStates, fromState)
				t.TargetIndexes = slices.Delete(t.TargetIndexes, idx, idx+1)
				targetStates = slices.Delete(targetStates, idx, idx+1)
				t.cacheTargetStates.Store(&targetStates)
			} else {
				return ret
			}
		}
	}

	return Executed
}

func (t *Transition) emitHandler(
	from, to string, isFinal, isEnter bool, event string, args A,
) Result {
	t.latestHandlerToState = to
	ret, handlerCalled := t.Machine.handle(event, args, isFinal, isEnter, false)

	if handlerCalled && t.Machine.semLogger.IsSteps() {
		step := newStep(from, to, StepHandler, 0)
		step.IsFinal = isFinal
		step.IsEnter = isEnter
		t.addSteps(step)
	}
	return ret
}

func (t *Transition) emitFinalEvents() Result {
	finals := slices.Concat(t.Exits, t.Enters)

	for _, s := range finals {
		isEnter := slices.Contains(t.Enters, s)

		var handler string
		if isEnter {
			handler = s + SuffixState
			t.latestHandlerToState = s
		} else {
			handler = s + SuffixEnd
			t.latestHandlerToState = ""
		}

		ret, handlerCalled := t.Machine.handle(handler, t.Mutation.Args,
			true, isEnter, false)

		if handlerCalled && t.Machine.semLogger.IsSteps() {
			step := newStep("", s, StepHandler, 0)
			step.IsFinal = true
			step.IsEnter = isEnter
			t.addSteps(step)
		}

		// final handler cancel means timeout
		if ret == Canceled {
			return ret
		}
	}

	return Executed
}

func (t *Transition) emitStateStateEvents() Result {
	before := t.StatesBefore()
	after := t.TargetStates()
	var newAfter S

	for i := range before {
		for ii := range after {
			if before[i] == after[ii] {
				continue
			}

			handler := before[i] + after[ii]
			t.latestHandlerToState = ""
			ret, handlerCalled := t.Machine.handle(handler, t.Mutation.Args, false,
				false, false)

			if handlerCalled && t.Machine.semLogger.IsSteps() {
				step := newStep(before[i], after[ii], StepHandler, 0)
				t.addSteps(step)
			}

			if ret != Canceled {
				continue
			}

			// negotiation canceled
			if t.IsAuto() {
				if newAfter == nil {
					newAfter = slices.Clone(after)
				}

				// partial auto state acceptance
				idx := slices.Index(newAfter, after[ii])
				if idx == -1 {
					// already removed
					continue
				}
				t.TargetIndexes = slices.Delete(t.TargetIndexes, idx, idx+1)

				// update cache
				newAfter = slices.Delete(newAfter, idx, idx+1)
				t.cacheTargetStates.Store(&newAfter)

			} else {
				return ret
			}
		}
	}

	return Executed
}

func (t *Transition) emitEvents() Result {
	m := t.Machine
	result := Executed
	if !t.IsAccepted.Load() {
		result = Canceled
	}
	hasStateChanged := false
	called := t.CalledStates()
	hasHandlers := t.Machine.handlerLoopRunning.Load()
	logEverything := m.semLogger.Level() == LogEverything

	// tracers
	m.tracersMx.RLock()
	for i := 0; !t.Machine.IsDisposed() && i < len(t.Machine.tracers); i++ {
		t.Machine.tracers[i].TransitionStart(t)
	}
	m.tracersMx.RUnlock()

	// NEGOTIATION CALLS PHASE (cancellable)

	if hasHandlers || logEverything {

		// FooExit handlers
		if result != Canceled {
			result = t.emitExitEvents()
		}

		// FooEnter handlers
		if result != Canceled {
			result = t.emitEnterEvents()
		}

		// FooFoo handlers
		if result != Canceled && t.Type() != MutationRemove {
			result = t.emitSelfEvents()
		}

		// BarFoo
		if result != Canceled {
			result = t.emitStateStateEvents()
		}

		// none of the auto states has been accepted, so cancel
		if t.IsAuto() && len(t.TargetIndexes) == 0 {
			result = Canceled
		}

		// global AnyEnter handler
		if result != Canceled {
			result = t.emitHandler(StateAny, StateAny, false, true,
				StateAny+SuffixEnter, t.Mutation.Args)
		}
	}

	// skip for CanAdd and CanRemove
	if !t.Mutation.IsCheck {
		// TODO extract

		// recheck auto txs for canceled handlers, remove direct and transitive Add
		// relation
		if t.IsAuto() {
			rejected := StatesDiff(called, t.TargetStates())
			calledClean := StatesDiff(called, rejected)
			toSet := t.statesToSet(MutationAdd, calledClean)
			targetStates := m.resolver.TargetStates(t, toSet, m.StateNames())
			t.TargetIndexes = m.Index(targetStates)
			t.cacheTargetStates.Store(&targetStates)
			// TODO cache states before?
		}

		// FINAL HANDLERS (non cancellable)
		if result != Canceled {

			// mutate the clocks
			m.activeStatesMx.Lock()
			m.setActiveStates(called, t.TargetStates(), t.IsAuto())
			// gather new clock values, overwrite fake TimeAfter
			m.activeStatesMx.Unlock()

			// always correct TimeAfter
			t.TimeAfter = m.time(nil)

			if hasHandlers || logEverything || m.subs.HasWhenArgs() {
				// FooState
				// FooEnd
				result = t.emitFinalEvents()
			}

			// handle timeouts in final handlers the same as a panic
			// TODO test
			if result == Canceled {
				m.recoverFinalPhase()
				// TODO safe to continue?
			}

			hasStateChanged = !m.IsTime(t.TimeBefore, nil)
		} else {
			// always correct TimeAfter
			t.TimeAfter = m.time(nil)
		}

		// global AnyState handler
		if result != Canceled && (hasHandlers || logEverything) {
			result = t.emitHandler(StateAny, StateAny, true, true,
				StateAny+SuffixState, t.Mutation.Args)
		}

		// basic OnChange handler
		if onChange := m.onChange.Load(); onChange != nil {
			(*onChange)(m, t.TimeBefore, t.TimeAfter)
		}

		// AUTO STATES
		if result == Canceled {
			t.IsAccepted.Store(false)
		} else if !m.disposing.Load() && hasStateChanged && !t.IsAuto() &&
			!t.IsHealth() {

			autoMut, calledStates := m.resolver.NewAutoMutation()
			if autoMut != nil {
				m.log(LogOps, "[auto] %s", j(calledStates))
				m.PrependMut(autoMut)
			}
		}

		// cache for subscriptions, mind partially accepted auto states
		if t.IsAuto() {
			before := t.StatesBefore()
			t.cacheActivated = StatesDiff(m.activeStates, before)
			t.cacheDeactivated = StatesDiff(before, m.activeStates)
		} else {
			t.cacheActivated = t.Enters
			t.cacheDeactivated = t.Exits
		}
	} else if result == Canceled {
		t.IsAccepted.Store(false)
	}

	// collect previous log entries
	m.logEntriesLock.Lock()
	t.PreLogEntries = m.logEntries
	t.QueueLen = uint16(m.queueLen.Load())
	m.logEntries = nil
	m.logEntriesLock.Unlock()
	t.IsCompleted.Store(true)

	// tracers
	m.tracersMx.RLock()
	for i := 0; !t.Machine.IsDisposed() && i < len(t.Machine.tracers); i++ {
		t.Machine.tracers[i].TransitionEnd(t)
	}
	m.tracersMx.RUnlock()

	if result == Canceled {
		return Canceled
	} else if t.Mutation.IsCheck {
		return result
	}

	// TODO optimize: remove checks?
	if t.Type() == MutationRemove {
		if m.Not(called) {
			return Executed
		} else {
			// TODO error?
			return Canceled
		}
	} else {
		if m.Is(t.TargetStates()) {
			return Executed
		} else {
			// TODO error?
			return Canceled
		}
	}
}

func (t *Transition) setupAccepted() {
	m := t.Machine
	// Dropping states doesn't require an acceptance
	if t.Type() == MutationRemove {
		return
	}
	called := t.CalledStates()
	notAccepted := StatesDiff(called, t.TargetStates())
	// Auto-states can be set partially
	if t.IsAuto() {
		// partially accepted
		if len(notAccepted) < len(called) {
			return
		}
		// all rejected, reject the whole transition
		t.IsAccepted.Store(false)
	}

	if len(notAccepted) <= 0 {
		return
	}

	// accept if check and one of called is multi
	isMulti := false
	for _, s := range called {
		if m.schema[s].Multi {
			isMulti = true
			break
		}
	}
	if t.Mutation.IsCheck && isMulti {
		return
	}

	// no accepted

	t.IsAccepted.Store(false)
	m.log(LogOps, "[cancel:reject] %s", j(notAccepted))
	if t.isLogSteps() {
		// TODO optimize: stop early on cancel
		t.addSteps(newSteps("", notAccepted, StepCancel, 0)...)
	}
}

func (t *Transition) isLogSteps() bool {
	l := t.Machine.semLogger
	if t.Mutation.IsCheck && !l.IsCan() {
		return false
	}

	return l.IsSteps()
}

The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.