runtime

package

v1.10.6 Latest Latest Go to latest Published: Aug 2, 2023 License: BSD-3-Clause Imports: 4 Imported by: 17

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ava-labs/avalanchego

Links

Open Source Insights

README ¶

Virtual Machine Runtime Engine (VMRE)

The VMRE handles the lifecycle, compatibility and logging IO of a managed VM process.

How it works

The runtime.Initializer interface could be implemented to manage local or remote VM processes. This implementation is consumed by a gRPC server which serves the Runtime service. The server interacts with the underlying process and allows for the VM binary to communicate with AvalancheGo.

Subprocess VM management

The subprocess is currently the only supported Runtime implementation. It works by starting the VM's as a subprocess of AvalancheGo by os.Exec.

Workflow

VMRegistry calls the RPC Chain VM Factory.
Factory Starts an instanace of a VMRE server that consumes a runtime.Initializer interface implementation.
The address of this server is passed as a ENV variable AVALANCHE_VM_RUNTIME_ENGINE_ADDR via os.Exec which starts the VM binary.
The VM uses the address of the VMRE server to create a client.
Client sends a Initialize RPC informing the server of the Protocol Version and future Address of the RPC Chain VM server allowing it to perform a validation Handshake.
After the Handshake is complete the RPC Chain VM server is started which serves the ChainVM implementation.
The connection details for the RPC Chain VM server are now used to create an RPC Chain VM client.
ChainManager uses this VM client to bootstrap the chain powered by Snowman consensus.
To shutdown the VM runtime.Stop() sends a SIGTERM signal to the VM process.

Debugging

Process Not Found

When runtime is Bootstrapped handshake success is observed during the Initialize RPC. Process not found means that the runtime Client in the VM binary could not communicate with the runtime Server on AvalancheGo. This could be the result of networking issues or other error in Serve().

failed to register VM {"vmID": "tGas3T58KzdjcJ2iKSyiYsWiqYctRXaPTqBCA11BqEkNg8kPc", "error": "handshake failed: timeout"}

Protocol Version Mismatch

To ensure RPC compatibility the protocol version of AvalancheGo must match the subnet VM. To correct this error update the subnet VM's dependencies to the latest version AvalancheGo.

failed to register VM {"vmID": "tGas3T58KzdjcJ2iKSyiYsWiqYctRXaPTqBCA11BqEkNg8kPc", "error": "handshake failed: protocol version mismatch avalanchego: 19 vm: 18"}

Documentation ¶

Constants ¶

View Source

const (
	// Address of the runtime engine server.
	EngineAddressKey = "AVALANCHE_VM_RUNTIME_ENGINE_ADDR"

	// Duration before handshake timeout during bootstrap.
	DefaultHandshakeTimeout = 5 * time.Second

	// Duration of time to wait for graceful termination to complete.
	DefaultGracefulTimeout = 5 * time.Second
)

Variables ¶

View Source

var (
	ErrProtocolVersionMismatch = errors.New("protocol version mismatch")
	ErrHandshakeFailed         = errors.New("handshake failed")
	ErrInvalidConfig           = errors.New("invalid config")
	ErrProcessNotFound         = errors.New("vm process not found")
)

Functions ¶

This section is empty.

Types ¶

type Initializer ¶

type Initializer interface {
	// Initialize provides AvalancheGo with compatibility, networking and
	// process information of a VM.
	Initialize(ctx context.Context, protocolVersion uint, vmAddr string) error
}

type Manager ¶

type Manager interface {
	Tracker
	// Stop all managed VMs.
	Stop(ctx context.Context)
}

func NewManager ¶

func NewManager() Manager

NewManager returns manager of VM runtimes.

TODO: If a runtime exits before the call to `manager.Stop`, it would be nice to remove it from the current set.

type Stopper ¶

type Stopper interface {
	// Stop begins shutdown of a VM. This method must not block
	// and multiple calls to this method will result in no-op.
	Stop(ctx context.Context)
}

type Tracker ¶

type Tracker interface {
	// TrackRuntime adds a VM stopper to the manager.
	TrackRuntime(runtime Stopper)
}

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
subprocess

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL