api

package
v0.0.0-...-c32f71b Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: AGPL-3.0 Imports: 7 Imported by: 0

Documentation

Overview

Module for all interface shared by executor implementations

Index

Constants

This section is empty.

Variables

View Source
var DefaultRuntimeConfig = &RuntimeConfig{Config: &config.DefaultConfig, Time: &util.SystemTime{}}

RuntimeConfig with config.DefaultConfig and no executor

Functions

This section is empty.

Types

type Executor

type Executor interface {
	fmt.Stringer

	// Validate the executor configuration and store, if applicable, references to it
	//
	// This expects:
	//   - a valid reference to a RuntimeConfig with an initialized ExecutorConfig
	// It should:
	//   - Do as much validation as possible to make sure the following Executor.Init would not fail
	Load(logger log.Logger, rcfg *RuntimeConfig) error
	// Perform any init procedures, like connecting to a service
	//
	// This expects:
	//   - rcfg to contain the parsed configuration
	//   - to be only called once
	//
	// It should:
	//   - set RuntimeConfig.Executor to itself
	//   - do any init procedures required to start a server instance (blocking until ready)
	//   - treat ctx as the executor lifetime context and only derive background
	//     resource contexts from it, not from StartInstance/StopInstance contexts
	Init(ctx context.Context, logger log.Logger) error
	// Perform any safe cleanup of resources that appear like artifacts of the current instance configuration
	//
	// It expects:
	//   - be called after init
	//   - not be interrupted by any StartInstance or Shutdown calls
	// It should:
	//   - be blocking until either an irrecoverable error occurred or ctx is done
	//   - safely cleanup all artifact-like resources (instances, ...)
	Clean(ctx context.Context, logger log.Logger) error
	// Shutdown pool and all associated servers
	//
	// It expects:
	//   - be called after init
	//   - To be called once
	// It should:
	//   - be blocking until either ...
	//      - an irrecoverable error occurred, ctx is done or ...
	//      - server are shutdown and cleanup is done
	//   - cleanup all internal state, like connections to other services
	Shutdown(ctx context.Context, logger log.Logger) error
	// calculate system load factor relative to server loads.
	// The load factor must be an unsigned integer between `0` and `100`.
	// Think of it as a rounded percentage.
	//
	// It expects:
	//   - be called after init
	// It should:
	//   - be goroutine safe, serving stale data on concurrent requests (like prometheus endpoints)
	//     is fine
	//   - return [config.ErrLoadMethodUnsupported] if this method is not yet implemented
	LoadFactor(ctx context.Context, logger log.Logger) (uint32, error)
	// Get memory usage and CPU load per server process
	//
	// It expects:
	//   - be called after init
	//   - server point to an initialized server
	// It should:
	//   - be goroutine safe
	ServerStats(
		ctx context.Context,
		logger log.Logger,
		server *util.Server,
	) (uint64, float64, error)
	// Start a new server instance
	//
	// It expects:
	//   - variant to refer to an isabelle variant, may be ignored if executor doesn't support multiple variants
	//   - be called after init
	// It should:
	//   - be goroutine safe
	//   - attach the monitoring client to the server
	//   - Start a new isabelle server instance (State is allowed to be ready)
	//   - block until server is ready to accept connections.
	//     This was previously under the waitReady flag and is now the default behaviour
	//   - Cancel start if ctx is done
	StartInstance(ctx context.Context, logger log.Logger, variant string) (*util.Server, error)
	// Attach a client to a server, useful if client connections require a setup
	//
	// It expects:
	//   - be called after init
	//   - id to correspond to an existing server
	//   - server point to an initialized server
	//   - client be non-nil
	//   - server's clientMtx to be locked
	//   - be only called once at a time per client
	// It should:
	//   - be goroutine safe
	//   - either connect the client to the server or fail
	//   - perform the handshake with the server if the connection is established
	//   - if context is done, fail and cancel connection attempt
	AttachClient(
		ctx context.Context,
		logger log.Logger,
		server *util.Server,
		client *isalink.IsaClient,
	) error
	// Stop a server instance
	//
	// It expects:
	//   - be called after init
	//   - server point to an initialized server
	//   - be called only once per server instance
	// It should:
	//   - be goroutine safe
	//   - Stop a isabelle server instance
	//   - Clean up all executor resources associated with this instance, like mounts
	//   - Block until either server is stopped or `ctx` is Done
	StopInstance(ctx context.Context, logger log.Logger, server *util.Server) error
	// Return the mapped location of a mount inside a particular server and a marker if remapped
	//
	// It expects:
	//   - be called after init
	//   - server point to an initialized server
	// It should:
	//   - be goroutine safe
	//   - be deterministic for a given [config.Config] and dir
	MapMount(dir string) (string, bool)
	// Return name of executor as string
	//
	// It should:
	//   - return a non-empty ascii, alphanumeric string
	//   - be static and invariable of executor instantiation parameters
	Name() string
	// Return version tag of supported isabelle version
	//
	// It expects:
	//   - be called after init
	// It should:
	//   - return a non-empty ascii, alphanumeric string.
	//     This string is either a valid isabelle version tag, e.g., 2025-2, or 'unknown'.
	//   - be goroutine safe
	Version() string
}

An executor is a component which can manage a pool of isabelle server instances.

It should internally manage the network accordingly to allow clients from the proxy to connect to the server instances. The interface itself is the contract between the broker and executors

type RuntimeConfig

type RuntimeConfig struct {
	*config.Config                   // parent config
	Executor       Executor          // reference to current [Executor]
	Time           util.TimeProvider // shared time provider
	Proc           *procfs.FS        // handle to procfs reader
}

parsed config, acts as **shared state** for all `broker` operations

Source Files

  • interface.go

Jump to

Keyboard shortcuts

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