states

README

/pkg/states

cd /

[!NOTE] asyncmachine-go is a declarative control flow library implementing AOP and Actor Model through a clock-based state machine.

/pkg/states contains common state definitions to make state-based API easier to compose and exchange. Additionally it offers tooling for "piping" states between state machines.

Available State Definitions

• BasicStatesDef: Start, Ready, Healthcheck
• ConnectedStatesDef: Client connection in 4 states
• DisposedStatesDef: Async disposal

Installation States

import ssam "github.com/pancsta/asyncmachine-go/pkg/states"

Examples

Inherit from BasicStatesDef manually

// inherit from RPC worker
ssStruct := am.StructMerge(ssam.BasicStruct, am.Struct{
    "Foo": {Require: am.S{"Bar"}},
    "Bar": {},
})
ssNames := am.SAdd(ssam.BasicStates.Names(), am.S{"Foo", "Bar"})

Inherit from BasicStatesDef via a definition

// MyMachStatesDef contains all the states of the MyMach state machine.
type MyMachStatesDef struct {
    *am.StatesBase

    State1 string
    State2 string

    // inherit from BasicStatesDef
    *ss.BasicStatesDef
}

// MyMachStruct represents all relations and properties of MyMachStates.
var MyMachStruct = StructMerge(
    // inherit from BasicStruct
    ss.BasicStruct,
    am.Struct{

        ssM.State1: {},
        ssM.State2: {
            Multi: true,
        },
})

Inherit from BasicStatesDef via the generator

$ am-gen --name MyMach \
  --states State1,State2 \
  --inherit basic

Piping

A "pipe" binds a handler of a source machine, to a mutation in a target machine. Currently, only final handlers are supported.

Each module can export their own pipes, like /pkg/rpc and /pkg/node.

Available Pipes

• BindConnected
• BindErr
• BindReady

Installation Pipes

import ampipe "github.com/pancsta/asyncmachine-go/pkg/states/pipes"

Using Pipes

ampipe.BindReady(rpcClient.Mach, myMach, "RpcReady", "")

Piping Manually

var source *am.Machine
var target *am.Machine

h := &struct {
    ReadyState am.HandlerFinal
    ReadyEnd   am.HandlerFinal
}{
    ReadyState: Add1(source, target, "Ready", "RpcReady"),
    ReadyEnd:   Remove1(source, target, "Ready", "RpcReady"),
}

source.BindHandlers(h)

Extending States

The purpose of this package is to share reusable states, but inheriting a definition isn't enough. States can also be extended on relations-level using helpers from states_utils.go (generated), although sometimes it's better to override a state (eg Ready).

import (
    am "github.com/pancsta/asyncmachine-go/pkg/machine"
    "github.com/pancsta/asyncmachine-go/pkg/states"
    ampipe "github.com/pancsta/asyncmachine-go/pkg/states/pipes"
)

// ...

MyMychStruct = am.Struct{

    // inject Client states into Connected
    "Connected": StateAdd(
        states.ConnectedStruct[states.ConnectedStates.Connected],
        am.State{
            Remove: S{"RetryingConn"},
            Add:    S{"Handshaking"},
    }),
}

Documentation

• godoc /pkg/states
• /examples/pipes

Status

Testing, semantically versioned.

monorepo

Go back to the monorepo root to continue reading.

Documentation

Overview

Package states provides reusable state definitions.

- basic - connected - disposed

Index

• Variables
• type BasicStatesDef
• type ConnectedGroupsDef
• type ConnectedStatesDef
• type DisposedGroupsDef
• type DisposedHandlers
  • func (h *DisposedHandlers) DisposingState(e *am.Event)
  • func (h *DisposedHandlers) RegisterDisposalEnter(e *am.Event) bool
  • func (h *DisposedHandlers) RegisterDisposalState(e *am.Event)
• type DisposedStatesDef
• type S
• type State

Variables

var (

	// ConnectedStates contains all the states for the Connected state set.
	ConnectedStates = cs

	// ConnectedGroups contains all the state groups for the Connected state set.
	ConnectedGroups = cg
)

var (

	// DisposedStates contains all the states for the Disposed machine.
	DisposedStates = ssD
	// DisposedGroups contains all the state groups for the Disposed machine.
	DisposedGroups = sgD
)

var (

	// BasicStates contains all the states for the Basic machine.
	BasicStates = ssB
)

var BasicStruct = am.Struct{

	ssB.Exception:         {Multi: true},
	ssB.ErrNetwork:        {Require: S{Exception}},
	ssB.ErrHandlerTimeout: {Require: S{Exception}},

	ssB.Start:       {},
	ssB.Ready:       {Require: S{ssB.Start}},
	ssB.Healthcheck: {Multi: true},
	ssB.Heartbeat:   {},
}

var ConnectedStruct = am.Struct{
	cs.Connecting: {
		Require: S{ssB.Start},
		Remove:  cg.Connected,
	},
	cs.Connected: {
		Require: S{ssB.Start},
		Remove:  cg.Connected,
	},
	cs.Disconnecting: {Remove: cg.Connected},
	cs.Disconnected: {
		Auto:   true,
		Remove: cg.Connected,
	},
}

ConnectedStruct represents all relations and properties of ConnectedStates.

var DisposedArgHandler = "DisposedArgHandler"

var DisposedStruct = am.Struct{
	ssD.RegisterDisposal: {},
	ssD.Disposing:        {Remove: sgD.Disposed},
	ssD.Disposed:         {Remove: sgD.Disposed},
}

DisposedStruct represents all relations and properties of DisposedStates.

var Exception = am.Exception

Exception is a type alias for the exception state.

var SAdd = am.SAdd

SAdd is a func alias for merging lists of states.

var StateAdd = am.StateAdd

StateAdd is a func alias for adding to an existing state definition.

var StateSet = am.StateSet

StateSet is a func alias for replacing parts of an existing state definition.

var StructMerge = am.StructMerge

StructMerge is a func alias for extending an existing state structure.

Types

type BasicStatesDef

type BasicStatesDef struct {
	*am.StatesBase

	// ErrNetwork indicates a generic network error.
	ErrNetwork string
	// ErrHandlerTimeout indicates one of state machine handlers has timed out.
	ErrHandlerTimeout string

	// Start indicates the machine should be working. Removing start can force
	// stop the machine.
	Start string
	// Ready indicates the machine meets criteria to perform work.
	Ready string
	// Healthcheck is a periodic request making sure that the machine is still
	// alive.
	Healthcheck string
	// Heartbeat is a periodic state which ensures integrity of the machine.
	Heartbeat string
}

BasicStatesDef contains all the basic states.

type ConnectedGroupsDef

type ConnectedGroupsDef struct {
	Connected S
}

ConnectedGroupsDef contains all the state groups of the Connected state set.

type ConnectedStatesDef

type ConnectedStatesDef struct {
	Connecting    string
	Connected     string
	Disconnecting string
	Disconnected  string

	*am.StatesBase
}

ConnectedStatesDef contains states for a connection status.

type DisposedGroupsDef

type DisposedGroupsDef struct {
	Disposed S
}

DisposedGroupsDef contains all the state groups Disposed state machine.

type DisposedHandlers

type DisposedHandlers struct {
	// DisposedHandlers is a list of handler for pkg/states.DisposedStates
	DisposedHandlers []am.HandlerDispose
}

func (*DisposedHandlers) DisposingState

func (h *DisposedHandlers) DisposingState(e *am.Event)

func (*DisposedHandlers) RegisterDisposalEnter

func (h *DisposedHandlers) RegisterDisposalEnter(e *am.Event) bool

func (*DisposedHandlers) RegisterDisposalState

func (h *DisposedHandlers) RegisterDisposalState(e *am.Event)

type DisposedStatesDef

type DisposedStatesDef struct {
	*am.StatesBase

	// RegisterDisposal registers a disposal handler passed under the
	// DisposedArgHandler key.
	RegisterDisposal string
	// Disposing indicates that the machine is during the disposal process.
	Disposing string
	// Disposed indicates that the machine has disposed allocated resoruces
	// and is ready to be garbage collected by calling [am.Machine.Dispose].
	Disposed string
}

DisposedStatesDef contains all the states of the Disposed state machine.

type S

type S = am.S

S is a type alias for a list of state names.

type State

type State = am.State

State is a type alias for a state definition. See am.State.