Client is a type representing an RPC client that interacts with a remote
am.Machine instance. Addr is the address the Client will connect to.CallCountuint64 CallRetries is the number of retries for a call. Default 15. CallRetryBackoff is the maximum time to wait between retries. Default 3s. CallRetryDelay is the time to wait between retries. Default 100ms. If
CallRetryBackoff is set, this is the initial delay, and doubles on each
retry. CallRetryTimeout is the maximum time to retry a call. Default 1m. CallTimeout is the maximum time to wait for a call to complete. Default 3s. ConnRetries is the number of retries for a connection. Default 15. ConnRetryBackoff is the maximum time to wait between retries. Default 3s. ConnRetryDelay is the time to wait between retries. Default 100ms. If
ConnRetryBackoff is set, this is the initial delay, and doubles on each
retry. ConnRetryTimeout is the maximum time to retry a connection. Default 1m. ConnTimeout is the maximum time to wait for a connection to be established.
Default 3s. Consumer is the optional consumer for deliveries. DisconnCooldown is the time to wait after notifying the server about
disconnecting before actually disconnecting. Default 10ms.DisconnTimeouttime.DurationExceptionHandler*ExceptionHandler HelloDelay between Connected and Handshaking. Default 0, useful for
rpc/Mux. LastMsgAt is the last received msg from the worker TODOLogEnabledboolMach*am.MachineNamestring NetMach is a remote am.Machine instance ReconnectOn decides if the client will try to [RetryingConn] after a
clean [Disconnect]. Synchronize machine times for every mutation (within a single sync msg). Only sync selected states.SyncMutationFilteringbool Skip schema synchronization / fetching. Only activete/deactivate (0-1) clock values will be sent. Skip syncing of these states. Args returns a list of registered typed args for a given machine.(*Client) CallRetryFailedState(e *am.Event)(*Client) ConnectedState(e *am.Event)(*Client) ConnectingState(e *am.Event)(*Client) DisconnectedEnter(e *am.Event) bool(*Client) DisconnectedState(e *am.Event)(*Client) DisconnectingEnter(e *am.Event) bool(*Client) DisconnectingState(e *am.Event)( Client) ExceptionEnter(e *am.Event) bool ExceptionState handles network errors and retries the connection. GetKind returns a kind of the RPC component (server / client).(*Client) HandshakeDoneEnter(e *am.Event) bool(*Client) HandshakeDoneState(e *am.Event)(*Client) HandshakingState(e *am.Event)(*Client) HealthcheckState(e *am.Event) IsPartial is true for NetMachs syncing only a subset of the Net Source's
states. RemoteBye is called by the server on a planned disconnect.
TODO take a reason / source event? RemoteSchemaChange is called by the server on a source machine schema change. RemoteSendPayload receives a payload from the server and triggers
WorkerPayload. The Consumer should bind his handlers and handle this state to
receive the data. RemoteSendingPayload triggers the WorkerDelivering state, which is an
optional indication that the server has started a data transmission to the
Client. This payload shouldn't contain the data itself, only the name and
token. RemoteUpdate updates the clock of NetMach from a cumulative diff. Only
called by the server. RemoteUpdateMutations updates the clock of NetMach from a list of mutations.
Only called by the server.(*Client) RetryingCallEnter(e *am.Event) bool RetryingConnState should be set without Connecting in the same tx Start connects the client to the server and initializes the worker.
Results in the Ready state.(*Client) StartEnd(e *am.Event)(*Client) StartState(e *am.Event) Stop disconnects the client from the server and disposes the worker.
waitTillExit: if passed, waits for the client to disconnect using the
context. Sync requests non-diff clock values from the remote machine. Useful to call
after a batch of no-sync methods, eg [NetworkMachine.AddNS]. Sync doesn't
honor [ClientOpts.SyncMutations] and only returns clock values (so can be
used to skip mutation syncing within a period).(*Client) WorkerPayloadEnter(e *am.Event) bool(*Client) WorkerPayloadState(e *am.Event)
*Client : github.com/pancsta/asyncmachine-go/pkg/rpc/states.ConsumerHandlers
func NewClient(ctx context.Context, netSrcAddr string, name string, netSrcSchema am.Schema, opts *ClientOpts) (*Client, error)
func github.com/pancsta/asyncmachine-go/internal/testing.NewRpcClient(t *testing.T, ctx context.Context, addr string, netSrcSchema am.Schema, consumer *am.Machine) *Client
func github.com/pancsta/asyncmachine-go/internal/testing.NewRpcTest(t *testing.T, ctx context.Context, netSrc *am.Machine, consumer *am.Machine) (*am.Machine, *Server, *Client)
func github.com/pancsta/asyncmachine-go/tools/repl.(*Repl).ListMachines(filters *repl.ListFilters) ([]*Client, error)
func github.com/pancsta/asyncmachine-go/internal/testing.RpcGet[G](t *testing.T, c *Client, name server.GetField, defVal G) G
func github.com/pancsta/asyncmachine-go/internal/testing.RpcShutdown(ctx context.Context, c *Client, s *Server)
Only sync selected states. Consumer is an optional target for the [states.SendPayload] state. Enable client-side mutation filtering by performing relations resolution
based on locally active states. Doesn't work with [ClientOpts.NoSchema].
TODO not implemented yet Make this client schema-less (infer an empty one for tracked states). Parent is a parent state machine for a new Client state machine. See
[am.Opts]. Skip syncing of these states. Sync machine time for every mutation. Disables
[ClientOpts.SyncShallowClocks]. Only activete/deactivate (0-1) clock values will be sent.
func NewClient(ctx context.Context, netSrcAddr string, name string, netSrcSchema am.Schema, opts *ClientOpts) (*Client, error)
ExceptionHandler is a shared exception handler for RPC server and
client.ExceptionHandler*am.ExceptionHandler(*ExceptionHandler) ExceptionEnter(e *am.Event) bool ExceptionState is a final entry handler for the StateException state.
Args:
- err error: The error that caused the StateException state.
- panic *ExceptionArgsPanic: Optional details about the panic.
MsgSrvPayload is the server sending a payload to the client. Data is the payload data. The Consumer has to know the type. Destination is an optional machine ID that is supposed to receive the
payload. Useful when using rpc.Mux. Name is used to distinguish different payload types at the destination. Source is the machine ID that sent the payload. SourceTx is transition ID. Token is a unique random ID for the payload. Autofilled by the server.
func (*Client).RemoteSendingPayload(_ *rpc2.Client, payload *MsgSrvPayload, _ *MsgEmpty) error
func (*Client).RemoteSendPayload(_ *rpc2.Client, payload *MsgSrvPayload, _ *MsgEmpty) error
func (*Server).SendPayload(ctx context.Context, event *am.Event, payload *MsgSrvPayload) error
MsgSrvUpdate is the server telling the client about a net source's update. Checksum is the last digit of (TimeSum + QueueTick + MachTick) Indexes of incremented states. MachTick is an incremental diff for the machine tick. TODO optimize: for shallow clocks
Active []bool
QueueTick is an incremental diff for the queue tick. Clock diffs of incremented states.
TODO optimize: []uint16 and send 2 updates when needed
func (*Client).RemoteUpdate(_ *rpc2.Client, update *MsgSrvUpdate, _ *MsgEmpty) error
MuxNewServerFn is a function to create a new RPC server for each incoming
connection.
func NewMux(ctx context.Context, name string, newServerFn MuxNewServerFn, opts *MuxOpts) (*Mux, error)
NetworkMachine is a subset of `pkg/machine#Machine` for RPC. Lacks the queue
and other local methods. Most methods are clock-based, thus executed locally.
NetworkMachine implements [am.Api]. If true, the machine will print all exceptions to stdout. Default: true.
Requires an ExceptionHandler binding and Machine.PanicToException set. ActiveStates returns a copy of the currently active states. Add is [am.Api.Add]. Add1 is [am.Api.Add1]. Add1NS is a single state version of AddNS. AddBreakpoint is [am.Api.AddBreakpoint]. AddBreakpoint1 is [am.Api.AddBreakpoint1]. AddErr is [am.Api.AddErr]. AddErrState is [am.Api.AddErrState]. AddNS is a NoSync method - an efficient way for adding states, as it
doesn't wait for, nor transfers a response. Because of which it doesn't
update the clock. Use Sync() to update the clock after a batch of AddNS
calls. Any is [am.Api.Any]. Any1 is [am.Api.Any1]. BindHandlers is [am.Api.BindHandlers].
NetworkMachine supports only pipe handlers (final ones, without negotiation). BindTracer is [am.Machine.BindTracer].
NetworkMachine tracers cannot mutate synchronously, as network machines
don't have a queue and WILL deadlock when nested. CanAdd is [am.Api.CanAdd]. CanAdd1 is [am.Api.CanAdd1]. CanRemove is [am.Api.CanRemove]. CanRemove1 is [am.Api.CanRemove1]. Clock returns current machine's clock, a state-keyed map of ticks. If states
are passed, only the ticks of the passed states are returned. Ctx return worker's root context. DetachHandlers is [am.Api.DetachHandlers]. DetachTracer is [am.Api.DetachTracer]. Dispose disposes the machine and all its emitters. You can wait for the
completion of the disposal with `<-mach.WhenDisposed`. Err returns the last error. EvAdd is [am.Api.EvAdd]. EvAdd1 is [am.Api.EvAdd1]. EvAddErr is [am.Api.EvAddErr]. EvAddErrState is [am.Api.EvAddErrState]. EvRemove is [am.Api.EvRemove]. EvRemove1 is [am.Api.EvRemove1]. EvToggle is [am.Api.EvToggle]. EvToggle1 is [am.Api.EvToggle1]. Export exports the machine state: id, time and state names. Groups is [am.Api.Groups]. Has is [am.Api.Has]. Has1 is [am.Api.Has1]. HasHandlers is [am.Api.HasHandlers]. Id returns the machine's id.(*NetworkMachine) Index(states am.S) []int Index1 returns the index of a state in the machine's StateNames() list. Inspect returns a multi-line string representation of the machine (states,
relations, clock).
states: param for ordered or partial results. Is is [am.Api.Is]. Is1 is [am.Api.Is1]. IsClock is [am.Api.IsClock]. IsDisposed returns true if the machine has been disposed. IsErr is [am.Api.IsErr]. IsTime is [am.Api.IsTime]. Log logs is a local logger. MachineTick is [am.Api.MachineTick]. MustParseStates parses the states and returns them as a list.
Panics when a state is not defined. It's an usafe equivalent of VerifyStates. NewStateCtx returns a new sub-context, bound to the current clock's tick of
the passed state.
Context cancels when the state has been de-activated, or right away,
if it isn't currently active.
State contexts are used to check state expirations and should be checked
often inside goroutines.
TODO log reader Not is [am.Api.Not]. Not1 is [am.Api.No1]. OnDispose is [am.Api.OnDispose]. ParentId returns the id of the parent machine (if any). ParseStates is [am.Api.ParseStates]. QueueLen is [am.Api.QueueLen]. QueueTick is [am.Api.QueueTick]. RemoteId returns the ID of the remote state machine. Remove is [am.Api.Remove]. Remove1 is [am.Api.Remove1]. Schema returns a copy of machine's state structure.(*NetworkMachine) SemLogger() am.SemLogger Set is [am.Api.Set]. StateNames returns a copy of all the state names.(*NetworkMachine) StateNamesMatch(re *regexp.Regexp) am.S StatesVerified returns true if the state names have been ordered
using VerifyStates. String returns a one line representation of the currently active states,
with their clock values. Inactive states are omitted.
Eg: (Foo:1 Bar:3) StringAll returns a one line representation of all the states, with their
clock values. Inactive states are in square brackets.
Eg: (Foo:1 Bar:3)[Baz:2] Switch is [am.Api.Switch]. Tags returns machine's tags, a list of unstructured strings without spaces. Tick returns the current tick for a given state. Time returns machine's time, a list of ticks per state. Returned value
includes the specified states, or all the states if nil. Toggle is [am.Api.Toggle]. Toggle1 is [am.Api.Toggle1]. Tracers is [am.Api.Tracers]. Transition is [am.Machine.Transition]. WasClock is [am.Api.WasClock]. WasTime is [am.Api.WasTime]. When is [am.Api.When]. When1 is an alias to When() for a single state.
See When. WhenArgs returns a channel that will be closed when the passed state
becomes active with all the passed args. Args are compared using the native
'=='. It's meant to be used with async Multi states, to filter out
a specific completion.
ctx: optional context that will close the channel when done. WhenDisposed returns a channel that will be closed when the machine is
disposed. Requires bound handlers. Use Machine.Disposed in case no handlers
have been bound. WhenErr is [am.Api.WhenErr]. WhenNot returns a channel that will be closed when all the passed states
become inactive or the machine gets disposed.
ctx: optional context that will close the channel early. WhenNot1 is an alias to WhenNot() for a single state.
See WhenNot. WhenQuery returns a channel that will be closed when the passed [clockCheck]
function returns true. [clockCheck] should be a pure function and
non-blocking.`
ctx: optional context that will close the channel early.(*NetworkMachine) WhenQueue(tick am.Result) <-chan struct{} WhenTicks waits N ticks of a single state (relative to now). Uses WhenTime
underneath.
ctx: optional context that will close the channel early.moon WhenTime returns a channel that will be closed when all the passed states
have passed the specified time. The time is a logical clock of the state.
Machine time can be sourced from [Machine.Time](), or [Machine.Clock]().
ctx: optional context that will close the channel early. WhenTime1 waits till ticks for a single state equal the given value (or
more).
ctx: optional context that will close the channel early.
*NetworkMachine : github.com/pancsta/asyncmachine-go/pkg/machine.Api
*NetworkMachine : expvar.Var
*NetworkMachine : fmt.Stringer
func NewNetworkMachine(ctx context.Context, id string, conn NetMachConn, schema am.Schema, stateNames am.S, parent *am.Machine, tags []string, filterMutations bool) (*NetworkMachine, *NetMachInternal, error)
func github.com/pancsta/asyncmachine-go/tools/repl.(*Repl).NetMach(machId string) *NetworkMachine
optional channel to send the address to, once ready optional dir path to save the address file as addrDir/mach-id.addr optional typed args instance. Requires ArgsPrefix optional prefix for typesafe args. Requires Args. optional channel to send err to, once ready
func MachRepl(mach am.Api, addr string, opts *ReplOpts) error
Typed arguments struct pointerArgsPrefixstring Parent is a parent state machine for a new Server state machine. See
[am.Opts]. PayloadState is a state for the server to listen on, to deliver payloads
to the client. The client activates this state to request a payload from
the worker. Default: am/rpc/states/WorkerStates.SendPayload.
func NewServer(ctx context.Context, addr string, name string, netSrcMach am.Api, opts *ServerOpts) (*Server, error)
Package-Level Functions (total 23)
AddErr detects sentinels from error msgs and calls the proper error setter.
TODO also return error for compat
BindServer binds RpcReady and ClientConnected with Add/Remove, to custom
states.
BindServerMulti binds RpcReady, ClientConnected, and ClientDisconnected.
RpcReady is Add/Remove, the other two are Add-only to passed multi states.
BindServerRpcReady bind RpcReady using Add to a custom multi state.
Checksum calculates a short checksum of current machine time and ticks.
GetClientId returns an RPC Client machine ID from a name. This ID will be
used to handshake the server.
LogArgs is an args logger for A.
MachRepl sets up a machine for a REPL connection, which allows for
mutations, like any other RPC connection. See [/tools/cmd/arpc] for usage.
This function is considered a debugging helper and can panic.
addr: address to listen on, default to 127.0.0.1:0
addrDir: optional dir path to save the address file as addrDir/mach-id.addr
addrCh: optional channel to send the address to, once ready
errCh: optional channel for errors
MachReplEnv sets up a machine for a REPL connection in case AM_REPL_ADDR env
var is set. See MachRepl.
NewClient creates a new RPC client and exposes a remote state machine as
a remote worker, with a subst of the API under Client.NetMach. Optionally
takes a consumer, which is a state machine with a WorkerPayload state. See
states.ConsumerStates.
TODO optimize with msgpack
NewMux initializes a Mux instance to handle RPC server creation for incoming
connections with the given parameters.
newServerFn: when nil, [Mux.Source] needs to be set manually before calling
[Mux.Start].
NewNetworkMachine creates a new instance of a NetworkMachine.
NewServer creates a new RPC server, bound to a worker machine.
The source machine has to implement [states.NetSourceStatesDef] interface.
ParseArgs extracts A from [am.Event.Args][APrefix].
Pass prepares [am.A] from A to pass to further mutations.
PassRpc prepares [am.A] from A to pass over RPC.
TrafficMeter measures the traffic of a listener and forwards it to a
destination. Results are sent to the [counter] channel. Useful for testing
and benchmarking.
The pages are generated with Goldsv0.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.
