engine

type AcceptController interface {
	// PauseAccept stops accepting new connections. Existing connections continue.
	PauseAccept() error
	// ResumeAccept resumes accepting new connections after a pause.
	ResumeAccept() error
}

type CapabilityProfile struct {
	// OS is the operating system name (e.g. "linux").
	OS string
	// KernelVersion is the full kernel version string (e.g. "5.15.0-91-generic").
	KernelVersion string
	// KernelMajor is the major kernel version number.
	KernelMajor int
	// KernelMinor is the minor kernel version number.
	KernelMinor int
	// IOUringTier is the detected io_uring capability tier (None through Optional).
	IOUringTier Tier
	// EpollAvailable is true if epoll is supported on this system.
	EpollAvailable bool
	// MultishotAccept is true if io_uring multishot accept is available (kernel 5.19+).
	MultishotAccept bool
	// MultishotRecv is true if io_uring multishot recv is available (kernel 5.19+).
	MultishotRecv bool
	// ProvidedBuffers is true if io_uring provided buffer rings are available (kernel 5.19+).
	ProvidedBuffers bool
	// SQPoll is true if io_uring SQ polling mode is available (kernel 6.0+).
	SQPoll bool
	// CoopTaskrun is true if IORING_SETUP_COOP_TASKRUN is available (kernel 5.19+).
	CoopTaskrun bool
	// SingleIssuer is true if IORING_SETUP_SINGLE_ISSUER is available (kernel 6.0+).
	SingleIssuer bool
	// LinkedSQEs is true if io_uring linked SQE chains are supported.
	LinkedSQEs bool
	// DeferTaskrun is true if IORING_SETUP_DEFER_TASKRUN is available (kernel 6.1+).
	DeferTaskrun bool
	// FixedFiles is true if io_uring fixed file descriptors are available.
	FixedFiles bool
	// SendZC is true if io_uring zero-copy send is available.
	SendZC bool
	// NumCPU is the number of logical CPUs.
	NumCPU int
	// NUMANodes is the number of NUMA nodes detected.
	NUMANodes int
}

type Engine interface {
	// Listen starts the engine and blocks until ctx is canceled or a fatal
	// error occurs. The engine begins accepting connections on the configured address.
	Listen(ctx context.Context) error
	// Shutdown gracefully drains in-flight connections. The provided context
	// controls the deadline; if it expires, remaining connections are closed.
	Shutdown(ctx context.Context) error
	// Metrics returns a point-in-time snapshot of engine performance counters.
	Metrics() EngineMetrics
	// Type returns the engine type identifier (IOUring, Epoll, Adaptive, or Std).
	Type() EngineType
	// Addr returns the bound listener address, or nil if not yet listening.
	Addr() net.Addr
}

type EngineMetrics struct {
	// RequestCount is the cumulative number of requests handled by this engine.
	RequestCount uint64
	// ActiveConnections is the current number of open connections.
	ActiveConnections int64
	// ErrorCount is the cumulative number of connection-level or protocol errors.
	ErrorCount uint64
	// Throughput is the recent requests-per-second rate.
	Throughput float64
	// LatencyP50 is the 50th-percentile (median) request latency.
	LatencyP50 time.Duration
	// LatencyP99 is the 99th-percentile request latency.
	LatencyP99 time.Duration
	// LatencyP999 is the 99.9th-percentile request latency.
	LatencyP999 time.Duration
}

type EngineType uint8 //nolint:revive // user-approved name

type EventLoopProvider interface {
	// NumWorkers returns the number of worker event loops available for
	// driver FD registration. This is typically equal to the engine's
	// configured worker count (one per CPU core).
	NumWorkers() int
	// WorkerLoop returns the WorkerLoop for worker n, where 0 <= n < NumWorkers().
	// Calling WorkerLoop with an out-of-range index panics.
	WorkerLoop(n int) WorkerLoop
}

type Protocol uint8

type SwitchFreezer interface {
	// FreezeSwitching prevents the adaptive engine from switching.
	FreezeSwitching()
	// UnfreezeSwitching allows engine switching to resume.
	UnfreezeSwitching()
}

type Tier uint8

type WorkerLoop interface {
	// RegisterConn adds fd to the worker's interest set and installs the
	// data and close callbacks. The fd is expected to be already connected
	// and in non-blocking mode. Returns an error if fd is already registered
	// on this or another worker.
	RegisterConn(fd int, onRecv func([]byte), onClose func(error)) error
	// UnregisterConn removes fd from the worker's interest set and triggers
	// the onClose callback (with a nil error) after any in-flight operations
	// complete. The caller is responsible for closing the fd itself.
	UnregisterConn(fd int) error
	// Write enqueues data for transmission on fd. The call does not block on
	// the kernel send buffer: data is buffered and flushed asynchronously by
	// the worker. Returns [ErrQueueFull] if the worker's outbound queue is
	// saturated. The data slice may be retained by the worker until the
	// write completes; callers must not modify it after calling Write.
	Write(fd int, data []byte) error
	// CPUID returns the CPU this worker is pinned to, or -1 if the worker is
	// not pinned. Drivers may use this to co-locate allocations (e.g.,
	// NUMA-aware buffers) with the worker.
	CPUID() int
}