feat(machine): allow for partial auto states via handlers (#208)

Author: pancsta

docs/cookbook.md

@@ -82,7 +82,7 @@ func (h *Handlers) AnyFoo(e *am.Event) {}
 
 ```go
 // always called as a transition from Any state to Any state
-func (h *Handlers) AnyAny(e *am.Event) bool {}
+func (h *Handlers) AnyEnter(e *am.Event) bool {}
 ```
 
 ## Global final handler

docs/manual.md

@@ -584,7 +584,7 @@ goroutine, with a timeout of [`Machine.HandlerTimeout`](https://pkg.go.dev/githu
 ```go
 // can Foo activate?
 func (h *Handlers) FooEnter(e *am.Event) bool {}
-// when Foo active, can Bar activate?
+// with Foo active, can Bar activate?
 func (h *Handlers) FooBar(e *am.Event) {}
 // Foo activates
 func (h *Handlers) FooState(e *am.Event) {}
@@ -597,8 +597,6 @@ func (h *Handlers) FooEnd(e *am.Event) {}
 List of handlers during a transition from `Foo` to `Bar`, in the order of execution:
 
 - `FooExit` - [negotiation handler](#negotiation-handlers)
-- `FooAny` - [negotiation handler](#negotiation-handlers)
-- `AnyBar` - [negotiation handler](#negotiation-handlers)
 - `BarEnter` - [negotiation handler](#negotiation-handlers)
 - `FooBar` - [negotiation handler](#negotiation-handlers)
 - `FooEnd` - [final handler](#final-handlers)
@@ -611,14 +609,13 @@ which can be set via [`am.Opts`](https://pkg.go.dev/github.com/pancsta/asyncmach
 
 ### Self Handlers
 
-Self handler is a final handler for states which were active **before and after** a transition (all no-change active
-states). The name is a doubled name of the state (eg `FooFoo`).
+Self handler is a negotiation handler for states which were active **before and after** a transition (all no-change
+active states). The name is a doubled name of the state (eg `FooFoo`).
 
 List of handlers during a transition from `Foo` to `Foo Bar`, in the order of execution:
 
-- `AnyBar` - [negotiation handler](#negotiation-handlers)
 - `BarEnter` - [negotiation handler](#negotiation-handlers)
-- `FooFoo` - [final handler](#final-handlers) and **self handler**
+- `FooFoo` - [negotiation handler](#negotiation-handlers) and **self handler**
 - `BarState` - [final handler](#final-handlers)
 
 Self handlers provide a simple alternative to [`Multi` states](#multi-states), while fully maintaining [state clocks](#clock-and-context).
@@ -754,13 +751,18 @@ end
 ### Negotiation Handlers
 
 ```go
+// can Foo activate?
 func (h *Handlers) FooEnter(e *am.Event) bool {}
+// can Foo de-activate?
 func (h *Handlers) FooExit(e *am.Event) bool {}
+// with Bar active, can Foo activate?
+func (h *Handlers) BarFoo(e *am.Event) bool {}
 ```
 
-**Negotiation handlers** `Enter` and `Exit` are called for every state which is going to be activated or de-activated. They
-are allowed to cancel a transition by optionally returning `false`. **Negotiation handlers** are limited to read-only
-operations, or at least to side effects free ones. Their purpose is to make sure that
+**Negotiation handlers** `Enter` and `Exit` are called for every state which is going to be activated or de-activated.
+State-state handler (eg `FooBar`) are `Foo` is active and `Bar` wants to activate. They are allowed to cancel a
+transition by optionally returning `false`. **Negotiation handlers** are limited to read-only operations, or at least to
+side effects free ones. Their purpose is to make sure that
 [final transition handlers](#final-handlers) are good to go.
 
 ```go
@@ -812,10 +814,6 @@ mach.Add1("Foo", nil) // ->am.Canceled
 ```go
 func (h *Handlers) FooState(e *am.Event) {}
 func (h *Handlers) FooEnd(e *am.Event) {}
-func (h *Handlers) FooBar(e *am.Event) {}
-func (h *Handlers) BarFoo(e *am.Event) {}
-func (h *Handlers) AnyFoo(e *am.Event) {}
-func (h *Handlers) FooAny(e *am.Event) {}
 ```
 
 Final handlers `State` and `End` are where the main handler logic resides. After the transition gets accepted by
@@ -858,10 +856,10 @@ func (h *Handlers) ProcessingFileState(e *am.Event) {
 
 ### Global Handlers
 
-`AnyAny` is the first negotiation handler and always gets executed.
+`AnyEnter` is the first negotiation handler and always gets executed.
 
 ```go
-func (d *Debugger) AnyAny(e *am.Event) bool {
+func (d *Debugger) AnyEnter(e *am.Event) bool {
     tx := e.Transition()
 
     // ...

pkg/machine/machine.go

@@ -569,7 +569,7 @@ func (m *Machine) WhenArgs(
 	ch := make(chan struct{})
 
 	m.MustParseStates(S{state})
-	name := state + "State"
+	name := state + SuffixState
 
 	// locks
 	m.indexWhenArgsLock.Lock()
@@ -1173,7 +1173,7 @@ func (m *Machine) queueMutation(
 //
 // Note: usage of Eval is discouraged. But if you have to, use AM_DETECT_EVAL in
 // tests for deadlock detection. Most usages of eval can be replaced with
-// atomics.
+// atomics or returning from mutation via channels.
 func (m *Machine) Eval(source string, fn func(), ctx context.Context) bool {
 	if m.disposed.Load() {
 		return false
@@ -1349,7 +1349,12 @@ func (m *Machine) BindHandlers(handlers any) error {
 	h := m.newHandler(handlers, name, &v, methodNames)
 	old := m.getHandlers(false)
 	m.setHandlers(false, append(old, h))
-	m.log(LogOps, "[handlers] bind %s", name)
+	if name != "" {
+		m.log(LogOps, "[handlers] bind %s", name)
+	} else {
+		// index for anon handlers
+		m.log(LogOps, "[handlers] bind %d", len(old))
+	}
 
 	return nil
 }
@@ -1959,7 +1964,7 @@ func (m *Machine) processWhenArgs(e *Event) {
 
 		argNames := jw(slices.AppendSeq(S{}, maps.Keys(binding.args)), ",")
 		// FooState -> Foo
-		name := e.Name[0 : len(e.Name)-len("State")]
+		name := e.Name[0 : len(e.Name)-len(SuffixState)]
 		m.log(LogOps, "[whenArgs:match] %s (%s)", name, argNames)
 		// args match - doDispose and close outside the mutex
 		chToClose = append(chToClose, binding.ch)
@@ -2327,8 +2332,8 @@ func (m *Machine) processHandlers(e *Event) (Result, bool) {
 		case timeout:
 
 			return Canceled, handlerCalled
-		case strings.HasSuffix(e.Name, "State"):
-		case strings.HasSuffix(e.Name, "End"):
+		case strings.HasSuffix(e.Name, SuffixState):
+		case strings.HasSuffix(e.Name, SuffixEnd):
 			// returns from State and End handlers are ignored
 		default:
 			if !ret {