package node

Import Path
	/pkg/node (on go.dev)

Dependency Relation
	imports 21 packages, and imported by one package

Involved Source Files

	  d node.go
		Package node provides distributed worker pools with supervisors.

	    node_client.go
	    node_worker.go
	    supervisor.go
	    supervisor_misc.go
Package-Level Type Names (total 9)

	/* sort by: alphabet | popularity */
	 type A (struct)
		A is a struct for node arguments. It's a typesafe alternative to [am.A].

		Fields (total 14)
			BootAddr string
				BootAddr is the local address of the Bootstrap machine.

			Bootstrap *bootstrap
				Bootstrap is the RPC machine used to connect WorkerRpc to the Supervisor.

			Dispose bool
				Dispose the worker.

			Id string
				Id is a machine ID.

			LocalAddr string
				LocalAddr is the public address of a Supervisor or WorkerRpc.

			NodesList []string
				NodesList is a list of available nodes (supervisors' public RPC addresses).

			PublicAddr string
				PublicAddr is the public address of a Supervisor or WorkerRpc.

			SuperRpcId string
				SuperRpcId is a machine ID of the super RPC client.

			WorkerAddr string
				WorkerAddr is an index for WorkerInfo.

			WorkerInfo *workerInfo
				WorkerInfo describes a worker.

			WorkerRpc *rpc.Client
				WorkerRpc is the RPC client connected to a WorkerRpc.

			WorkerRpcId string
				WorkerRpcId is a machine ID of the worker RPC client.

			WorkerState WorkerState
				WorkerState is a requested state of workers, eg for listings.

			WorkersCh chan<- []*workerInfo
				WorkersCh returns a list of workers. This channel has to be buffered.

		As Outputs Of (at least one exported)
			func ParseArgs(args am.A) *A
		As Inputs Of (at least 2)
			func Pass(args *A) am.A
			func PassRpc(args *A) am.A

	 type ARpc (struct)
		ARpc is a subset of A, that can be passed over RPC.

		Fields (total 7)
			BootAddr string
				BootAddr is the local address of the Bootstrap machine.

			Id string
				Id is a machine ID.

			LocalAddr string
				LocalAddr is the public address of a Supervisor, Worker, or [bootstrap].

			NodesList []string
				NodesList is a list of available nodes (supervisors' public RPC addresses).

			PublicAddr string
				PublicAddr is the public address of a Supervisor or Worker.

			SuperRpcId string
				SuperRpcId is a machine ID of the super RPC client.

			WorkerRpcId string
				WorkerRpcId is a machine ID of the worker RPC client.


	 type Client (struct)
		Client is a node client, connecting to a supervisor and then a worker.

		Fields (total 9)
			ConnTimeout time.Duration
				ConnTimeout is the time to wait for an outbound connection to be
				established. Default is 5 seconds.

			ExceptionHandler *am.ExceptionHandler
			LeaveSuper bool
				LeaveSuper is a flag to leave the supervisor after connecting to the
				worker. TODO

			LogEnabled bool
			Mach *am.Machine
			Name string
			RpcSuper *rpc.Client
			RpcWorker *rpc.Client
			SuperAddr string
		Methods (total 12)
			(*Client) Dispose(ctx context.Context)
				Dispose deallocates resources and stops the client's RPC connections.

			( Client) ExceptionState(e *machine.Event)
				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.

			(*Client) ReqWorker(ctx context.Context) error
				ReqWorker sends a request to add a "WorkerRequested" state to the client's
				state machine and waits for "WorkerReady" state.

			(*Client) Start(nodesList []string)
				Start initializes the client with a list of node addresses to connect to.

			(*Client) StartEnd(e *am.Event)
			(*Client) StartEnter(e *am.Event) bool
			(*Client) StartState(e *am.Event)
			(*Client) Stop(ctx context.Context)
				Stop halts the client's connection to both the supervisor and worker RPCs,
				and removes the client state from the state machine.

			(*Client) WorkerPayloadEnter(e *am.Event) bool
			(*Client) WorkerPayloadState(e *am.Event)
				WorkerPayloadState handles both Supervisor and Worker inbound payloads, but
				this shared code only deals with [states.ClientStatesDef.WorkerRequested].

			(*Client) WorkerRequestedEnter(e *am.Event) bool
			(*Client) WorkerRequestedState(e *am.Event)
		Implements (at least one exported)
			*Client : github.com/pancsta/asyncmachine-go/pkg/rpc/states.ConsumerHandlers
		As Outputs Of (at least one exported)
			func NewClient(ctx context.Context, clientId string, workerKind string, workerSchema am.Schema, opts *ClientOpts) (*Client, error)

	 type ClientOpts (struct)
		ClientOpts provides configuration options for creating a new client state
		machine.

		Fields (total 4)
			ClientSchema am.Schema
				Optional schema for the client. Should extend [states.ClientStatesDef].

			ClientStates am.S
				Optional state names for ClientSchema.

			Parent am.Api
				Parent is a parent state machine for a new client state machine. See
				[am.Opts].

			Tags []string
		As Inputs Of (at least one exported)
			func NewClient(ctx context.Context, clientId string, workerKind string, workerSchema am.Schema, opts *ClientOpts) (*Client, error)

	 type Supervisor (struct)

		Fields (total 33)
			ClientSendPayloadState am.HandlerFinal
			ConnTimeout time.Duration
				ConnTimeout is the time to wait for an outbound connection to be
				established. Default is 5s.

			DeliveryTimeout time.Duration
				DeliveryTimeout is a timeout for RPC delivery.

			ExceptionHandler *am.ExceptionHandler
			HealthcheckPause time.Duration
				HealthcheckPause is the time between trying to get a Healtcheck response
				from a worker.

			HealthcheckState am.HandlerFinal
			Heartbeat time.Duration
				Heartbeat is the frequency of the Heartbeat state, which normalized the
				pool and checks workers. Default 1m.

			KillWorkerState am.HandlerFinal
			LocalAddr string
				LocalAddr is the address for the local RPC server to listen on. The
				effective address is at [LocalRpc.Addr].

			LocalRpc *rpc.Server
				LocalRpc is the local RPC server, used by other supervisors to connect.
				TODO rpc/mux

			LogEnabled bool
			Mach *am.Machine
			Max int
				Max is the maximum number of workers. Default is 10.

			MaxClientWorkers int
				MaxClientWorkers is the maximum number of workers per 1 client. Defaults to
				Max.

			Min int
				Min is the minimum number of workers. Default is 2.

			Name string
				Name is the name of the supervisor.

			OpTimeout time.Duration
				OpTimeout is the default timeout for operations (eg getters).

			PoolPause time.Duration
				PoolPause is the time to wait between normalizing the pool. Default is 5s.

			PublicAddr string
				PublicAddr is the address for the public RPC server to listen on. The
				effective address is at [PublicMux.Addr].

			PublicMux *rpc.Mux
				PublicMux is the public listener to create RPC servers for each client.

			PublicRpcs map[string]*rpc.Server
				PublicRpc are the public RPC servers of connected clients, indexed by
				remote addresses.

			SuperSendPayloadState am.HandlerFinal
			TestFork func(string) error
			TestKill func(string) error
			Warm int
				Warm is the number of warm (ready) workers. Default is 5.

			WorkerBin []string
				WorkerBin is the path and args to the worker binary.

			WorkerCheckInterval time.Duration
				WorkerCheckInterval defines how often to pull a worker's state. Default 1s.

			WorkerErrKill int
				WorkerErrKill is the number of errors to kill a worker. Default is 3.

			WorkerErrRecent time.Duration
				WorkerErrRecent is the time to consider recent errors. Default is 1m.

			WorkerErrTtl time.Duration
				WorkerErrTtl is the time to keep worker errors in memory. Default is 10m.

			WorkerGoneState am.HandlerFinal
			WorkerKind string
				WorkerKind is the kind of worker this supervisor is managing.

			WorkerReadyState am.HandlerFinal
		Methods (total 36)
			(*Supervisor) CheckPool() bool
				CheckPool tries to set pool as ready and normalizes it, if not.

			(*Supervisor) ClientConnectedState(e *am.Event)
			(*Supervisor) ClientDisconnectedEnter(e *am.Event) bool
			(*Supervisor) ClientDisconnectedState(e *am.Event)
			(*Supervisor) Dispose()
			(*Supervisor) ErrWorkerState(e *am.Event)
			( Supervisor) ExceptionState(e *machine.Event)
				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.

			(*Supervisor) ForkWorkerEnter(e *am.Event) bool
			(*Supervisor) ForkWorkerState(e *am.Event)
			(*Supervisor) ForkingWorkerEnter(e *am.Event) bool
			(*Supervisor) ForkingWorkerState(e *am.Event)
			(*Supervisor) HeartbeatState(e *am.Event)
			(*Supervisor) KillingWorkerEnter(e *am.Event) bool
			(*Supervisor) KillingWorkerState(e *am.Event)
			(*Supervisor) ListWorkersEnter(e *am.Event) bool
			(*Supervisor) ListWorkersState(e *am.Event)
			(*Supervisor) NormalizingPoolState(e *am.Event)
			(*Supervisor) PoolReadyEnter(e *am.Event) bool
			(*Supervisor) PoolReadyExit(e *am.Event) bool
			(*Supervisor) ProvideWorkerEnter(e *am.Event) bool
			(*Supervisor) ProvideWorkerState(e *am.Event)
			(*Supervisor) SetPool(min, max, warm, maxPerClient int)
				SetPool sets the pool parameters with defaults.

			(*Supervisor) SetWorkerEnter(e *am.Event) bool
			(*Supervisor) SetWorkerState(e *am.Event)
			(*Supervisor) Start(publicAddr string)
			(*Supervisor) StartEnd(e *am.Event)
			(*Supervisor) StartEnter(e *am.Event) bool
			(*Supervisor) StartState(e *am.Event)
			(*Supervisor) Stop()
			(*Supervisor) WorkerConnectedEnter(e *am.Event) bool
			(*Supervisor) WorkerConnectedState(e *am.Event)
			(*Supervisor) WorkerForkedEnter(e *am.Event) bool
			(*Supervisor) WorkerForkedState(e *am.Event)
			(*Supervisor) WorkerKilledEnter(e *am.Event) bool
			(*Supervisor) WorkerKilledState(e *am.Event)
			(*Supervisor) Workers(ctx context.Context, state WorkerState) ([]*workerInfo, error)
				Workers returns a list of workers in a desired state. If [ctx] expires, it
				will reutrn nil, nil.

		As Outputs Of (at least one exported)
			func NewSupervisor(ctx context.Context, workerKind string, workerBin []string, workerSchema am.Schema, opts *SupervisorOpts) (*Supervisor, error)

	 type SupervisorOpts (struct)

		Fields (total 3)
			InstanceNum int
				InstanceNum is the number of this instance in a failsafe config, used for
				the ID.

			Parent am.Api
				Parent is a parent state machine for a new Supervisor state machine. See
				[am.Opts].

			Tags []string
				TODO

		As Inputs Of (at least one exported)
			func NewSupervisor(ctx context.Context, workerKind string, workerBin []string, workerSchema am.Schema, opts *SupervisorOpts) (*Supervisor, error)

	 type Worker (struct)

		Fields (total 13)
			AcceptClient string
				AcceptClient is the ID of a client, passed by the supervisor. Worker should
				only accept connections from this client.

			BootAddr string
				BootAddr is the address of the bootstrap machine.

			BootRpc *rpc.Client
				BootRpc is the RPC client connection to bootstrap machine, which passes
				connection info to the Supervisor.

			ConnTimeout time.Duration
				ConnTimeout is the time to wait for an outbound connection to be
				established.

			DeliveryTimeout time.Duration
			ExceptionHandler *am.ExceptionHandler
			Kind string
			LocalAddr string
				LocalAddr is the address of the local RPC server.

			LocalRpc *rpc.Server
				LocalRpc is the local RPC server, used by the Supervisor to connect.

			Mach *am.Machine
			Name string
			PublicAddr string
				PublicAddr is the address of the public RPC server.

			PublicRpc *rpc.Server
				PublicRpc is the public RPC server, used by the Client to connect.

		Methods (total 14)
			(*Worker) ErrNetworkState(e *am.Event)
			( Worker) ExceptionState(e *machine.Event)
				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.

			(*Worker) HealthcheckState(e *am.Event)
			(*Worker) LocalRpcReadyState(e *am.Event)
			(*Worker) PublicRpcReadyState(e *am.Event)
			(*Worker) RpcReadyState(e *am.Event)
			(*Worker) SendPayloadEnter(e *am.Event) bool
			(*Worker) ServeClientEnter(e *am.Event) bool
			(*Worker) ServeClientState(e *am.Event)
			(*Worker) Start(bootAddr string) am.Result
				Start connects the worker to the bootstrap RPC.

			(*Worker) StartEnd(e *am.Event)
			(*Worker) StartEnter(e *am.Event) bool
			(*Worker) StartState(e *am.Event)
			(*Worker) Stop(dispose bool)
				Stop halts the worker's state machine and optionally disposes of its
				resources based on the dispose flag.

		As Outputs Of (at least one exported)
			func NewWorker(ctx context.Context, kind string, workerStruct am.Schema, stateNames am.S, opts *WorkerOpts) (*Worker, error)

	 type WorkerOpts (struct)

		Fields (total 2)
			Parent am.Api
				Parent is a parent state machine for a new Worker state machine. See
				[am.Opts].

			Tags []string
				TODO

		As Inputs Of (at least one exported)
			func NewWorker(ctx context.Context, kind string, workerStruct am.Schema, stateNames am.S, opts *WorkerOpts) (*Worker, error)

	 type WorkerState string (basic type)
		states of a worker

		As Inputs Of (at least one exported)
			func (*Supervisor).Workers(ctx context.Context, state WorkerState) ([]*workerInfo, error)
		As Types Of (total 5)
			const StateBusy
			const StateIdle
			const StateIniting
			const StateReady
			const StateRpc


Package-Level Functions (total 14)

	 func AddErrPool(mach *am.Machine, err error, args am.A) error
		AddErrPool wraps an error in the ErrPool sentinel and adds to a machine.
		TODO add event param

	 func AddErrPoolStr(mach *am.Machine, msg string, args am.A) error
		AddErrPoolStr wraps a msg in the ErrPool sentinel and adds to a machine.
		TODO add event param

	 func AddErrRpc(mach *am.Machine, err error, args am.A) error
		AddErrRpc wraps an error in the ErrRpc sentinel and adds to a machine.
		TODO add event param

	 func AddErrWorker(event *am.Event, mach *am.Machine, err error, args am.A) error
		AddErrWorker wraps an error in the ErrWorker sentinel and adds to a machine.

	 func AddErrWorkerStr(mach *am.Machine, msg string, args am.A) error
		AddErrWorkerStr wraps a msg in the ErrWorker sentinel and adds to a machine.
		TODO add event param

	 func GetSuperClientId(name string) string
		GetSuperClientId returns a Node Supervisor machine ID from a name.

	 func GetWorkerClientId(name string) string
		GetWorkerClientId returns a Node Client machine ID from a name.

	 func LogArgs(args am.A) map[string]string
		LogArgs is an args logger for A and [rpc.A].

	 func NewClient(ctx context.Context, clientId string, workerKind string, workerSchema am.Schema, opts *ClientOpts) (*Client, error)
		NewClient creates a new Client instance with the provided context, id,
		workerKind, state dependencies, and options. Returns a pointer to the Client
		instance and an error if any validation or initialization fails.
		
		workerKind: any string used to build IDs and address workers

	 func NewSupervisor(ctx context.Context, workerKind string, workerBin []string, workerSchema am.Schema, opts *SupervisorOpts) (*Supervisor, error)
		NewSupervisor initializes and returns a new Supervisor instance with
		specified context, worker attributes, and options.
		
		workerBin: path to run the worker binary file (for [exec.CommandContext]).

	 func NewWorker(ctx context.Context, kind string, workerStruct am.Schema, stateNames am.S, opts *WorkerOpts) (*Worker, error)
		NewWorker initializes a new Worker instance and returns it, or an error if
		validation fails.

	 func ParseArgs(args am.A) *A
		ParseArgs extracts A from [am.Event.Args][APrefix].

	 func Pass(args *A) am.A
		Pass prepares [am.A] from A to pass to further mutations.

	 func PassRpc(args *A) am.A
		PassRpc prepares [am.A] from A to pass over RPC.


Package-Level Variables (total 8)

	  var ErrHeartbeat error
	  var ErrPool error
	  var ErrRpc error
	  var ErrWorker error
	  var ErrWorkerConn error
	  var ErrWorkerHealth error
	  var ErrWorkerKill error
	  var ErrWorkerMissing error
Package-Level Constants (total 8)

	const APrefix = "am_node"
	const EnvAmNodeLogClient = "AM_NODE_LOG_CLIENT"
		EnvAmNodeLogClient enables extra logging for node client.

	const EnvAmNodeLogSupervisor = "AM_NODE_LOG_SUPERVISOR"
		EnvAmNodeLogSupervisor enables extra logging for node supervisor.

	const StateBusy WorkerState = "busy"
	const StateIdle WorkerState = "idle"
	const StateIniting WorkerState = "initing"
	const StateReady WorkerState = "ready"
	const StateRpc WorkerState = "rpc"

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.