helpers

package
v0.19.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 11, 2026 License: MIT Imports: 24 Imported by: 9

README

/pkg/helpers

cd /

[!NOTE] asyncmachine-go is a pathless control-flow graph with a consensus (AOP, actor model, state-machine).

/pkg/helpers is the swiss army knife for async state machines. It encapsulates many low-level details of /pkg/machine and provide easy to reason about functions. It specifically deals with machine time and multi states, which can be quite verbose.

Highlights:

Installation

// prod
import amhelp "github.com/pancsta/asyncmachine-go/pkg/helpers"
// tests
import amhelp "github.com/pancsta/asyncmachine-go/pkg/helpers/testing"

Synchronous Calls

Synchronous wrappers of async state machine calls, which assume a single, blocking scenario controlled with context. Multi states are handled automatically.

  • Add1Sync
  • Add1Async

Example - add state StateNameSelected and wait until it becomes active

res := amhelp.Add1Sync(ctx, mach, ss.StateNameSelected, am.A{"state": state})
print(mach.Is1(ss.StateNameSelected)) // true
print(res) // am.Executed or am.Canceled, never am.Queued

Example - wait for ScrollToTx, triggered by ScrollToMutTx

res := amhelp.Add1Async(ctx, mach, ss.ScrollToTx, ss.ScrollToMutTx, am.A{
    "state": state,
    "fwd":   true,
})

print(mach.Is1(ss.ScrollToTx)) // true
print(res) // am.Executed or am.Canceled, never am.Queued

Debugging Helpers

Activate debugging in 1 line - either for a single machine, or for the whole process.

  • EnableDebugging
  • SetLogLevel
  • MachDebugEnv
  • MachDebug
  • Healthcheck
  • IsDebug

Example - enable dbg telemetry using conventional env vars.

// set env vars
amhelp.EnableDebugging(true)
// debug
amhelp.MachDebugEnv(mach)

Waiting Helpers

Waiting helpers mostly provide wrappers for when methods in select statements with a state context, and timeout context. State context is checked before, and timeout transformed into am.ErrTimeout. It reduces state context checking, if used as a first call after a blocking call / start (which is a common case).

  • WaitForAll
  • WaitForErrAll
  • WaitForAny
  • WaitForErrAny
  • GroupWhen1
  • Wait
  • ExecAndClose

Example - wait for bootstrap RPC to become ready.

//
err := amhelp.WaitForAll(ctx, s.ConnTimeout,
    boot.server.Mach.When1(ssrpc.ServerStates.RpcReady, nil))
if ctx.Err() != nil {
    return // expired
}
if err != nil {
    AddErrWorker(s.Mach, err, Pass(argsOut))
    return
}

Example - wait for all clients to be ready.

var clients []*node.Client

amhelp.WaitForAll(t, ctx, 2*time.Second,
    amhelp.GroupWhen1(clients, ssC.Ready, nil)...)

Example - wait 1s with a state context.

if !amhelp.Wait(ctx, 1*time.Second) {
    return // expired
}
// wait ok

Example - wait for Foo, Bar, or Exception.

ctx := client.Mach.NewStateCtx("Start")
err := amhelp.WaitForErrAll(ctx, 1*time.Second, mach,
        mach.When1("Foo", nil),
        mach.When1("Bar", nil))
if ctx.Err() != nil {
    // no err
    return nil // expired
}
if err != nil {
    // either timeout happened or Exception has been activated
    return err
}

Failsafe Request Object

Failsafe mutation requests use failsafe-go policies when mutating a state machine. Useful for network communication, or when waiting on a state isn't an option, but also helps with overloaded machines and populated queues. Policies can be customized and MutRequest objects cloned.

  • NewReqAdd
  • NewReqAdd1
  • NewReqRemove
  • NewReqRemove1
  • NewMutRequest

Example - try to add state WorkerRequested with 10 retries, 100ms delay, 5s backoff, and 5s max duration.

// failsafe worker request
_, err := amhelp.NewReqAdd1(c.Mach, ssC.WorkerRequested, nil).Run(ctx)
if err != nil {
    return err
}

Test Helpers

Test helpers mostly provide assertions for stretchr/testify, but also wrappers for regular helpers which go t.Fatal on errors (to save some lines).

  • AssertIs
  • AssertIs1
  • AssertNot
  • AssertNot1
  • AssertNoErrNow
  • AssertNoErrEver
  • AssertErr
  • MachDebug
  • MachDebugEnv
  • Wait
  • WaitForAll
  • WaitForAny
  • WaitForErrAll
  • WaitForErrAny
  • GroupWhen1

Example - assert mach has ClientConnected active.

amhelpt.AssertIs1(t, mach, "ClientConnected")

Example - assert mach never had an error (not just currently).

amhelpt.AssertNoErrEver(t, mach)

Complete API

Package-Level Functions (total 56)

     func Activations(u uint64) int
     func Add1Async(ctx context.Context, mach am.Api, waitState string, addState string, args am.A) am.Result
     func Add1Sync(ctx context.Context, mach am.Api, state string, args am.A) am.Result
     func ArgsToArgs[T](src interface{}, dest T) T
     func ArgsToLogMap(args interface{}, maxLen int) map[string]string
     func AskAdd(mach am.Api, states am.S, args am.A) am.Result
     func AskAdd1(mach am.Api, state string, args am.A) am.Result
     func AskEvAdd(e *am.Event, mach am.Api, states am.S, args am.A) am.Result
     func AskEvAdd1(e *am.Event, mach am.Api, state string, args am.A) am.Result
     func AskEvRemove(e *am.Event, mach am.Api, states am.S, args am.A) am.Result
     func AskEvRemove1(e *am.Event, mach am.Api, state string, args am.A) am.Result
     func AskRemove(mach am.Api, states am.S, args am.A) am.Result
     func AskRemove1(mach am.Api, state string, args am.A) am.Result
     func CantAdd(mach am.Api, states am.S, args am.A) bool
     func CantAdd1(mach am.Api, state string, args am.A) bool
     func CantRemove(mach am.Api, states am.S, args am.A) bool
     func CantRemove1(mach am.Api, state string, args am.A) bool
     func CopySchema(source am.Schema, target *am.Machine, states am.S) error
     func CountRelations(state *am.State) int
     func EnableDebugging(stdout bool)
     func EvalGetter[T](ctx context.Context, source string, maxTries int, mach *am.Machine, eval func() (T, error)) (T, error)
     func ExecAndClose(fn func()) <-chan struct{}
     func GetTransitionStates(tx *am.Transition, index am.S) (added am.S, removed am.S, touched am.S)
     func GroupWhen1(machs []am.Api, state string, ctx context.Context) ([]<-chan struct{}, error)
     func Healthcheck(mach am.Api)
     func Implements(statesChecked, statesNeeded am.S) error
     func IndexesToStates(allStates am.S, indexes []int) am.S
     func Interval(ctx context.Context, length time.Duration, interval time.Duration, fn func() bool) error
     func IsDebug() bool
     func IsMulti(mach am.Api, state string) bool
     func IsTelemetry() bool
     func IsTestRunner() bool
     func MachDebug(mach am.Api, amDbgAddr string, logLvl am.LogLevel, stdout bool, semConfig *am.SemConfig)
     func MachDebugEnv(mach am.Api)
     func NewMirror(id string, flat bool, source *am.Machine, handlers any, states am.S) (*am.Machine, error)
     func NewMutRequest(mach am.Api, mutType am.MutationType, states am.S, args am.A) *MutRequest
     func NewReqAdd(mach am.Api, states am.S, args am.A) *MutRequest
     func NewReqAdd1(mach am.Api, state string, args am.A) *MutRequest
     func NewReqRemove(mach am.Api, states am.S, args am.A) *MutRequest
     func NewReqRemove1(mach am.Api, state string, args am.A) *MutRequest
     func NewStateLoop(mach *am.Machine, loopState string, optCheck func() bool) *StateLoop
     func Pool(limit int) *errgroup.Group
     func PrefixStates(schema am.Schema, prefix string, removeDups bool, optWhitelist, optBlacklist S) am.Schema
     func RemoveMulti(mach am.Api, state string) am.HandlerFinal
     func ResultToErr(result am.Result) error
     func SchemaHash(schema am.Schema) string
     func SemConfig(forceFull bool) *am.SemConfig
     func SetEnvLogLevel(level am.LogLevel)
     func StatesToIndexes(allStates am.S, states am.S) []int
     func TagValue(tags []string, key string) string
     func Wait(ctx context.Context, length time.Duration) bool
     func WaitForAll(ctx context.Context, timeout time.Duration, chans ...<-chan struct{}) error
     func WaitForAny(ctx context.Context, timeout time.Duration, chans ...<-chan struct{}) error
     func WaitForErrAll(ctx context.Context, timeout time.Duration, mach am.Api, chans ...<-chan struct{}) error
     func WaitForErrAny(ctx context.Context, timeout time.Duration, mach *am.Machine, chans ...<-chan struct{}) error

Package-Level Variables (only one)

      var SlogToMachLogOpts *slog.HandlerOptions

Package-Level Constants (total 11)

    const EnvAmHealthcheck = "AM_HEALTHCHECK"
    const EnvAmLogArgs = "AM_LOG_ARGS"
    const EnvAmLogChecks = "AM_LOG_CHECKS"
    const EnvAmLogFile = "AM_LOG_FILE"
    const EnvAmLogFull = "AM_LOG_FULL"
    const EnvAmLogGraph = "AM_LOG_GRAPH"
    const EnvAmLogQueued = "AM_LOG_QUEUED"
    const EnvAmLogStateCtx = "AM_LOG_STATE_CTX"
    const EnvAmLogSteps = "AM_LOG_STEPS"
    const EnvAmLogWhen = "AM_LOG_WHEN"
    const EnvAmTestRunner = "AM_TEST_RUNNER"

Documentation

Status

Testing, not semantically versioned.

monorepo

Go back to the monorepo root to continue reading.

Documentation

Overview

Package helpers is a set of useful functions when working with async state machines.

Index

Constants

View Source 
const (
	// EnvAmLogPrint prints machine log to stdout.
	EnvAmLogPrint = "AM_LOG_PRINT"
	// EnvAmHealthcheck enables a healthcheck ticker for every debugged machine.
	EnvAmHealthcheck = "AM_HEALTHCHECK"
	// EnvAmTestRunner indicates the main test tunner, disables any telemetry.
	EnvAmTestRunner = "AM_TEST_RUNNER"
	// EnvAmLogFull enables all the features of [am.SemLogger].
	EnvAmLogFull = "AM_LOG_FULL"
	// EnvAmLogSteps logs transition steps.
	// See [am.SemLogger.EnableSteps].
	// "1" | "" (default)
	EnvAmLogSteps = "AM_LOG_STEPS"
	// EnvAmLogGraph logs the graph structure (mutation traces, pipes, RPC, etc).
	// See [am.SemLogger.EnableGraph].
	// "1" | "" (default)
	EnvAmLogGraph = "AM_LOG_GRAPH"
	// EnvAmLogChecks logs Can methods. See [am.SemLogger.EnableCan].
	// "1" | "" (default)
	EnvAmLogChecks = "AM_LOG_CHECKS"
	// EnvAmLogQueued logs queued mutations. See [am.SemLogger.EnableQueued].
	// "1" | "" (default)
	EnvAmLogQueued = "AM_LOG_QUEUED"
	// EnvAmLogArgs logs mutation args. See [am.SemLogger.EnableArgs].
	// "1" | "" (default)
	EnvAmLogArgs = "AM_LOG_ARGS"
	// EnvAmLogWhen logs When methods. See [am.SemLogger.EnableWhen].
	// "1" | "" (default)
	EnvAmLogWhen = "AM_LOG_WHEN"
	// EnvAmLogStateCtx logs state ctxs. See [am.SemLogger.EnableStateCtx].
	// "1" | "" (default)
	EnvAmLogStateCtx = "AM_LOG_STATE_CTX"
	// EnvAmLogFile enables file logging (using machine ID as the name).
	// "1" | "" (default)
	EnvAmLogFile = "AM_LOG_FILE"
)

Variables

View Source 
var SlogToMachLogOpts = &slog.HandlerOptions{
	ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {

		if a.Key == slog.TimeKey || a.Key == slog.LevelKey {
			return slog.Attr{}
		}
		return a
	},
}

SlogToMachLogOpts complements SlogToMachLog.

Functions

func Activations added in v0.8.0 

func Activations(u uint64) int

Activations return the number of state activations from the number of ticks passed.

func Add1Async added in v0.15.0 

func Add1Async(
	ctx context.Context, mach am.Api, waitState string,
	addState string, args ...am.A,
) bool

Add1Async is AddAsync for a single state.

func Add1Sync added in v0.15.0 

func Add1Sync(
	ctx context.Context, mach am.Api, state string, args ...am.A,
) bool

Add1Sync is AddSync for a single state.

func AddAsync added in v0.18.9 

func AddAsync(
	ctx context.Context, mach am.Api, waitState string,
	addStates S, args ...am.A,
) bool

AddAsync add initial states from an async op and waits for the final state to become active (can be a Multi state).

func AddSync added in v0.18.9 

func AddSync(
	ctx context.Context, mach am.Api, states S, args ...am.A,
) bool

AddSync activates a state and waits until it becomes activate, or canceled. Supports queued rejections, expiration ctx and returns as am.Canceled.

func ArgsNames added in v0.19.0 

func ArgsNames(args []am.ArgsApi) ([]string, error)

ArgsNames collect a flat list of names from a slice of typesafe arguments. Uses JSON encoding, useful for REPLs.

func ArgsToLogMap added in v0.8.0 

func ArgsToLogMap(args any, maxLen int) map[string]string

ArgsToLogMap converts a typed arguments struct to a map of strings using `log` tags as keys, and their casted string values.

func ArgsUnmarshal added in v0.19.0 

func ArgsUnmarshal[G am.ArgsApi](args am.A, def G) am.A

ArgsUnmarshal deserializes JSON [args] into an instance of [def] under a "State.Arg" index. Useful for REPLs.

func AskAdd added in v0.15.0 

func AskAdd(mach am.Api, states am.S, args am.A) am.Result

AskAdd will first check if a mutation isn't impossible and only then try to mutate the state machine. Causes the negotiation phase to execute twice. AskAdd BLOCKS. Useful to avoid canceled transitions.

See also am.Machine.CanAdd and CantAdd.

func AskAdd1 added in v0.15.0 

func AskAdd1(mach am.Api, state string, args am.A) am.Result

AskAdd1 is a single-state version of AskAdd.

func AskEvAdd added in v0.15.0 

func AskEvAdd(e *am.Event, mach am.Api, states am.S, args am.A) am.Result

AskEvAdd is a traced version of AskAdd.

func AskEvAdd1 added in v0.15.0 

func AskEvAdd1(e *am.Event, mach am.Api, state string, args am.A) am.Result

AskEvAdd1 is a traced version of AskAdd for a single state.

func AskEvRemove added in v0.15.0 

func AskEvRemove(e *am.Event, mach am.Api, states am.S, args am.A) am.Result

AskEvRemove is a traced version of AskRemove.

func AskEvRemove1 added in v0.15.0 

func AskEvRemove1(e *am.Event, mach am.Api, state string, args am.A) am.Result

AskEvRemove1 is a traced version of AskRemove for a single state.

func AskRemove added in v0.15.0 

func AskRemove(mach am.Api, states am.S, args am.A) am.Result

AskRemove will first check if a mutation isn't impossible and only then try to mutate the state machine. Causes the negotiation phase to execute twice. AskRemove BLOCKS. Useful to avoid canceled transitions.

See also am.Machine.CanRemove and CantRemove.

func AskRemove1 added in v0.15.0 

func AskRemove1(mach am.Api, state string, args am.A) am.Result

AskRemove1 is a single-state version of AskRemove.

func CantAdd added in v0.15.0 

func CantAdd(mach am.Api, states am.S, args am.A) bool

CantAdd will confirm that the mutation is impossible. Blocks.

func CantAdd1 added in v0.15.0 

func CantAdd1(mach am.Api, state string, args am.A) bool

CantAdd1 is a single-state version of CantAdd.

func CantRemove added in v0.15.0 

func CantRemove(mach am.Api, states am.S, args am.A) bool

CantRemove will confirm that the mutation is impossible. Blocks.

func CantRemove1 added in v0.15.0 

func CantRemove1(mach am.Api, state string, args am.A) bool

CantRemove1 is a single-state version of CantRemove.

func CopySchema added in v0.13.0 

func CopySchema(source am.Schema, target *am.Machine, states am.S) error

CopySchema copies states from the source to target schema, from the passed list of states. Returns a list of copied states, and an error. CopySchema verifies states.

func CountRelations added in v0.12.0 

func CountRelations(state *am.State) int

CountRelations will count all referenced states in all relations of the given state.

func Dispose added in v0.17.0 

func Dispose(mach am.Api)

Dispose triggers a machine disposal, using either the dedicated state set or the machine directly.

func DisposeBind added in v0.17.0 

func DisposeBind(mach am.Api, handler am.HandlerDispose)

DisposeBind registers a disposal handler, using either the dedicated state set or the machine directly.

func DisposeEv added in v0.18.0 

func DisposeEv(mach am.Api, e *am.Event)

DisposeEv is like DisposeEv, but accepts a source event.

func EnableDebugging added in v0.8.0 

func EnableDebugging(stdout bool)

EnableDebugging sets env vars for debugging tested machines with am-dbg on port 6831.

func EvAdd1Async added in v0.18.9 

func EvAdd1Async(
	ctx context.Context, e *am.Event, mach am.Api, waitState string,
	addState string, args ...am.A,
) bool

func EvAdd1Sync added in v0.18.0 

func EvAdd1Sync(
	ctx context.Context, e *am.Event, mach am.Api, state string, args ...am.A,
) bool

EvAdd1Sync is Add1Sync with an am.Event trace.

func EvAddAsync added in v0.18.9 

func EvAddAsync(
	ctx context.Context, e *am.Event, mach am.Api, waitState string,
	addStates S, args ...am.A,
) bool

func EvAddSync added in v0.18.9 

func EvAddSync(
	ctx context.Context, e *am.Event, mach am.Api, states S, args ...am.A,
) bool

EvAddSync is AddSync with an am.Event trace.

func EvRemove1Sync added in v0.18.9 

func EvRemove1Sync(
	ctx context.Context, e *am.Event, mach am.Api, state string, args ...am.A,
) bool

EvRemove1Sync is Remove1Sync with an am.Event trace.

func EvRemoveSync added in v0.18.9 

func EvRemoveSync(
	ctx context.Context, e *am.Event, mach am.Api, states S, args ...am.A,
) bool

EvRemoveSync is RemoveSync with an am.Event trace.

func EvalGetter added in v0.15.0 

func EvalGetter[T any](
	ctx context.Context, source string, maxTries int, mach *am.Machine,
	eval func() (T, error),
) (T, error)

EvalGetter is a syntax sugar for creating getters via Eval functions. Like any eval, it can end with ErrEvalTimeout. Getting values via channels passed to mutations is recommended and allows for a custom timeout.

func EvalSetter added in v0.18.9 

func EvalSetter(
	ctx context.Context, source string, maxTries int, mach *am.Machine,
	eval func() error,
) error

func ExecAndClose added in v0.8.0 

func ExecAndClose(fn func()) <-chan struct{}

ExecAndClose closes the chan when the function ends.

func GetTransitionStates added in v0.8.0 

func GetTransitionStates(
	tx *am.Transition, index am.S,
) (added am.S, removed am.S, touched am.S)

GetTransitionStates will extract added, removed, and touched states from transition's clock values and steps. Requires a state names index. Collecting touched states requires transition steps.

See also am.Transition.TimeIndexDiff and am.Transition.TimeIndexTouched.

func GroupWhen1 added in v0.8.0 

func GroupWhen1(
	machs []am.Api, state string, ctx context.Context,
) ([]<-chan struct{}, error)

GroupWhen1 will create wait channels for the same state in a group of machines, or return a am.ErrStateMissing.

func HandlerToState added in v0.18.0 

func HandlerToState(handler string) string

HandlerToState returns a state name from a handler name.

func Healthcheck added in v0.8.0 

func Healthcheck(mach am.Api)

Healthcheck adds a state to a machine every 5 seconds, until the context is done. This makes sure all the logs are pushed to the telemetry server. TODO use machine scheduler (once available))

func Implements added in v0.8.0 

func Implements(statesChecked, statesNeeded am.S) error

Implements checks is statesChecked implement statesNeeded. It's an equivalent of Machine.Has(), but for slices of state names, and with better error msgs.

func IndexesToStates 

func IndexesToStates(allStates am.S, indexes []int) am.S

IndexesToStates converts a list of state indexes to a list of state names, for a given machine.

func Interval added in v0.8.0 

func Interval(
	ctx context.Context, length time.Duration, interval time.Duration,
	fn func() bool,
) error

Interval runs a function at a given interval, for a given duration, or until the context is done. Returns nil if the duration has passed, or err is ctx is done. The function should return false to stop the interval.

func IsDebug added in v0.8.0 

func IsDebug() bool

IsDebug returns true if the process is in a "simple debug mode" via AM_DEBUG.

func IsMulti 

func IsMulti(mach am.Api, state string) bool

IsMulti returns true if a state is a multi state.

func IsTelemetry added in v0.8.0 

func IsTelemetry() bool

IsTelemetry returns true if the process is in telemetry debug mode.

func IsTestRunner added in v0.8.0 

func IsTestRunner() bool

func IsWasi added in v0.18.4 

func IsWasi() bool

IsWasi is true for WASI envs.

func IsWasm added in v0.18.0 

func IsWasm() bool

IsWasm is true for browser WASM.

func LogArgs added in v0.19.0 

func LogArgs(args am.A, maxLen int) map[string]string

LogArgs runs ArgsToLogMap on each am.A entry and returns a full log arg map. Useful for logging typed arguments.

func LogArgsMapper added in v0.19.0 

func LogArgsMapper(args am.A) map[string]string

LogArgsMapper is LogArgs implementing am.LogArgsMapperFn, so it fits into am.SemLogger. Typed args only.

func MachDebug 

func MachDebug(
	mach am.Api, amDbgAddr string, logLvl am.LogLevel, stdout bool,
	semConfig *am.SemConfig,
) error

MachDebug exports transition telemetry to an am-dbg instance listening at [amDbgAddr].

func MachDebugEnv 

func MachDebugEnv(mach am.Api) error

MachDebugEnv sets up a machine for debugging, based on env vars only: AM_DBG_ADDR, AM_LOG, AM_LOG_*, and AM_DEBUG. This function should be called right after the machine is created (to catch all the log entries).

func MachDebugWs added in v0.18.0 

func MachDebugWs(
	mach am.Api, amDbgAddr string, logLvl am.LogLevel, stdout bool,
	semConfig *am.SemConfig,
) error

MachDebugWs exports transition telemetry to an am-dbg instance listening on a WebSicjet at [amDbgAddr]. Useful for WASM.

func MachToSlog added in v0.18.0 

func MachToSlog(mach am.Api) *slog.Logger

MachToSlog exposes machine logger as slog.Logger.

func NewMirror added in v0.13.0 

func NewMirror(
	id string, flat bool, source *am.Machine, handlers any, states am.S,
) (*am.Machine, error)

NewMirror creates a submachine which mirrors the given source machine. If [flat] is true, only mutations changing the state will be propagated, along with the currently active states.

At this point, the handlers' struct needs to be defined manually with fields of type `am.HandlerFinal`.

[id] is optional.

func Pool added in v0.10.2 

func Pool(ctx context.Context, limit int) pond.TaskGroup

Pool creates a highly configurable pond pool. Use SubmitErr or Submit on the result.

func RandId added in v0.18.0 

func RandId(strLen int) string

RandId generates a random ID of the given length (defaults to 8).

func Remove1Sync added in v0.18.9 

func Remove1Sync(
	ctx context.Context, mach am.Api, state string, args ...am.A,
) bool

Remove1Sync is RemoveSync for a single state.

func RemoveMulti added in v0.8.0 

func RemoveMulti(mach am.Api, state string) am.HandlerFinal

RemoveMulti creates a final handler which removes a multi state from a machine. Useful to avoid FooState-Remove1-Foo repetition.

func RemoveSync added in v0.18.9 

func RemoveSync(
	ctx context.Context, mach am.Api, states S, args ...am.A,
) bool

RemoveSync activates a state and waits until it becomes activate, or canceled. Supports queued rejections, expiration ctx and returns as am.Canceled.

func ResultToErr added in v0.10.2 

func ResultToErr(result am.Result) error

func SchemaHash added in v0.13.0 

func SchemaHash(schema am.Schema) string

SchemaHash computes an MD5 hash of the passed schema. The order of states is not important.

func SchemaImplements added in v0.17.0 

func SchemaImplements(schema am.Schema, states am.S) error

SchemaImplements checks if a given schema implements a certain set of states.

func SemConfigEnv added in v0.17.0 

func SemConfigEnv(forceFull bool) *am.SemConfig

SemConfigEnv returns a SemConfigEnv based on env vars, or the [forceFull] flag.

func SetEnvLogLevel added in v0.15.0 

func SetEnvLogLevel(level am.LogLevel)

SetEnvLogLevel sets AM_LOG env var to the passed log level. It will affect all future state machines using MachDebugEnv.

func StatesToIndexes 

func StatesToIndexes(allStates am.S, states am.S) []int

StatesToIndexes converts a list of state names to a list of state indexes, for the given machine. It returns -1 for unknown states.

func TagValue added in v0.12.0 

func TagValue(tags []string, key string) string

TagValue returns the value part from a text tag "key:value". For tag without value, it returns the tag name.

func TagValueInt added in v0.17.1 

func TagValueInt(tags []string, key string) int

TagValueInt is like TagValue, but returns a formatted int.

func Wait added in v0.8.0 

func Wait(ctx context.Context, length time.Duration) bool

Wait waits for a duration, or until the context is done. Returns true if the duration has passed, or false if ctx is done.

func WaitForAll added in v0.8.0 

func WaitForAll(
	ctx context.Context, timeout time.Duration, chans ...<-chan struct{},
) error

WaitForAll waits for a list of channels to close, or until the context is done, or until the timeout is reached. Returns nil if all channels are closed, or ErrTimeout, or ctx.Err().

It's advised to check the state ctx after this call, as it usually means expiration and not a timeout.

func WaitForAny added in v0.8.0 

func WaitForAny(
	ctx context.Context, timeout time.Duration, chans ...<-chan struct{},
) error

WaitForAny waits for any of the channels to close, or until the context is done, or until the timeout is reached. Returns nil if any channel is closed, or ErrTimeout, or ctx.Err().

It's advised to check the state ctx after this call, as it usually means expiration and not a timeout.

This function uses reflection to wait for multiple channels at once.

func WaitForErrAll added in v0.8.0 

func WaitForErrAll(
	ctx context.Context, timeout time.Duration, mach am.Api,
	chans ...<-chan struct{},
) error

WaitForErrAll is like WaitForAll, but also waits on WhenErr of a passed machine. For state machines with error handling (like retry) it's recommended to use WaitForAll and measure ticks of am.StateException instead.

func WaitForErrAny added in v0.8.0 

func WaitForErrAny(
	ctx context.Context, timeout time.Duration, mach *am.Machine,
	chans ...<-chan struct{},
) error

WaitForErrAny is like WaitForAny, but also waits on WhenErr of a passed machine. For state machines with error handling (like retry) it's recommended to use WaitForAny and measure ticks of am.StateException instead.

func WhenFunc added in v0.19.0 

func WhenFunc(fn func()) <-chan struct{}

WhenFunc converts a blocking call to a broadcast channel, which can be used in `select`.

func WhenFuncOk added in v0.19.0 

func WhenFuncOk(fn func() bool) <-chan bool

WhenFuncOk converts a blocking call to a bool send channel, which can be used in `select`.

Types

type A added in v0.12.0 

type A = am.A

type ArgsUnmarshallerFn added in v0.19.0 

type ArgsUnmarshallerFn func(args am.A) am.A

func NewArgsUnmarshaller added in v0.19.0 

func NewArgsUnmarshaller(defs []am.ArgsApi) ArgsUnmarshallerFn

NewArgsUnmarshaller creates a new unmarshalling function for the provided argument [defs].

type Cond added in v0.12.0 

type Cond struct {

	// Only if all these states are active.
	Is S
	// Only if any of these groups of states are active.
	Any []S
	// Only if any of these states is active.
	Any1 S
	// Only if none of these states are active.
	Not S
	// Only if the clock is equal or higher then.
	Clock am.Clock
}

Cond is a set of state conditions, which when all met make the condition true.

func (Cond) Check added in v0.12.0 

func (c Cond) Check(mach am.Api) bool

Check compares the specified conditions against the passed machine. When mach is nil, Check returns false.

func (Cond) IsEmpty added in v0.12.0 

func (c Cond) IsEmpty() bool

IsEmpty returns false if no condition is defined.

func (Cond) String added in v0.12.0 

func (c Cond) String() string

type MachGroup added in v0.10.2 

type MachGroup []am.Api

func (*MachGroup) Is1 added in v0.10.2 

func (g *MachGroup) Is1(state string) bool

type MutRequest added in v0.8.0 

type MutRequest struct {
	Mach    am.Api
	MutType am.MutationType
	States  am.S
	Args    am.A
	Event   *am.Event

	// PolicyRetries is the max number of retries.
	PolicyRetries int
	// PolicyDelay is the delay before the first retry, then doubles.
	PolicyDelay time.Duration
	// PolicyBackoff is the max time to wait between retries.
	PolicyBackoff time.Duration
	// PolicyMaxDuration is the max time to wait for the mutation to be accepted.
	PolicyMaxDuration time.Duration
}

MutRequest is a failsafe request for a machine mutation. It supports retries, backoff, max duration, delay, and timeout policies. It will try to mutate the machine until the context is done, or the max duration is reached. Queued mutations are considered supported a success.

func NewMutRequest added in v0.8.0 

func NewMutRequest(
	mach am.Api, mutType am.MutationType, states am.S, args am.A,
) *MutRequest

NewMutRequest creates a new MutRequest with defaults - 10 retries, 100ms delay, 5s backoff, and 5s max duration.

func NewReqAdd added in v0.8.0 

func NewReqAdd(mach am.Api, states am.S, args am.A) *MutRequest

NewReqAdd creates a new failsafe request to add states to a machine. See See MutRequest for more info and NewMutRequest for the defaults.

func NewReqAdd1 added in v0.8.0 

func NewReqAdd1(mach am.Api, state string, args am.A) *MutRequest

NewReqAdd1 creates a new failsafe request to add a single state to a machine. See MutRequest for more info and NewMutRequest for the defaults.

func NewReqRemove added in v0.8.0 

func NewReqRemove(mach am.Api, states am.S, args am.A) *MutRequest

NewReqRemove creates a new failsafe request to remove states from a machine. See MutRequest for more info and NewMutRequest for the defaults.

func NewReqRemove1 added in v0.8.0 

func NewReqRemove1(mach am.Api, state string, args am.A) *MutRequest

NewReqRemove1 creates a new failsafe request to remove a single state from a machine. See MutRequest for more info and NewMutRequest for the defaults.

func (*MutRequest) Backoff added in v0.8.0 

func (r *MutRequest) Backoff(backoff time.Duration) *MutRequest

func (*MutRequest) Clone added in v0.8.0 

func (r *MutRequest) Clone(
	mach am.Api, mutType am.MutationType, states am.S, args am.A,
) *MutRequest

func (*MutRequest) Delay added in v0.8.0 

func (r *MutRequest) Delay(delay time.Duration) *MutRequest

func (*MutRequest) MaxDuration added in v0.8.0 

func (r *MutRequest) MaxDuration(maxDuration time.Duration) *MutRequest

func (*MutRequest) Retries added in v0.8.0 

func (r *MutRequest) Retries(retries int) *MutRequest

func (*MutRequest) Run added in v0.8.0 

func (r *MutRequest) Run(ctx context.Context) (am.Result, error)

Run blocks and executes the request. Returns when the transition wasn't am.Canceled, or until too many errors.

type S added in v0.12.0 

type S = am.S

type Schema added in v0.12.0 

type Schema = am.Schema

type SlogToMachLog added in v0.12.0 

type SlogToMachLog struct {
	Mach am.Api
}

SlogToMachLog allows to use the machine logger as a slog sink. 

a.loggerMach = slog.New(slog.NewTextHandler(
	amhelp.SlogToMachLog{Mach: mach}, amhelp.SlogToMachLogOpts))

func (SlogToMachLog) Write added in v0.12.0 

func (l SlogToMachLog) Write(p []byte) (n int, err error)

type StateLoop added in v0.12.0 

type StateLoop struct {
	ResetInterval time.Duration
	// max ticks
	Threshold int
	// contains filtered or unexported fields
}

TODO thread safety via atomics

func NewStateLoop added in v0.12.0 

func NewStateLoop(
	mach *am.Machine, loopState string, optCheck func() bool,
) *StateLoop

NewStateLoop helper creates a state loop guard bound to a specific state (eg Heartbeat), preventing infinite loops. It monitors context, off states, ticks of related "context states", and an optional check function. We can adjust Threshold and ResetInterval. Not thread safe ATM.

func (*StateLoop) Break added in v0.12.0 

func (l *StateLoop) Break()

Break breaks the loop.

func (*StateLoop) Ended added in v0.12.0 

func (l *StateLoop) Ended() bool

Ended returns the ended flag, but does not any context. Useful for negotiation handles which don't have state context yet.

func (*StateLoop) Ok added in v0.12.0 

func (l *StateLoop) Ok(ctx context.Context) bool

Ok returns true if the loop should continue.

func (*StateLoop) String added in v0.12.0 

func (l *StateLoop) String() string

func (*StateLoop) Sum added in v0.12.0 

func (l *StateLoop) Sum() uint64

Sum returns a sum of state time from all context states.

Source Files

View all Source files

Directories

Path Synopsis
Package testing provides testing helpers for state machines using testify.
 Package testing provides testing helpers for state machines using testify.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.