engine

Documentation

Overview

Package engine defines the core Engine interface and types.

Index

• type AcceptController
• type CapabilityProfile
  • func NewDefaultProfile() CapabilityProfile
• type Engine
• type EngineMetrics
• type EngineType
  • func (t EngineType) String() string
• type Protocol
  • func (p Protocol) String() string
• type SwitchFreezer
• type Tier
  • func (t Tier) Available() bool
  • func (t Tier) String() string

Types

type AcceptController

type AcceptController interface {
	PauseAccept() error
	ResumeAccept() error
}

AcceptController is implemented by engines that support dynamic accept control.

type CapabilityProfile

type CapabilityProfile struct {
	OS              string
	KernelVersion   string
	KernelMajor     int
	KernelMinor     int
	IOUringTier     Tier
	EpollAvailable  bool
	MultishotAccept bool
	MultishotRecv   bool
	ProvidedBuffers bool
	SQPoll          bool
	CoopTaskrun     bool
	SingleIssuer    bool
	LinkedSQEs      bool
	DeferTaskrun    bool
	FixedFiles      bool
	NumCPU          int
	NUMANodes       int
}

CapabilityProfile describes the capabilities detected on the current system.

func NewDefaultProfile

func NewDefaultProfile() CapabilityProfile

NewDefaultProfile returns a CapabilityProfile with safe defaults.

type Engine

type Engine interface {
	Listen(ctx context.Context) error
	Shutdown(ctx context.Context) error
	Metrics() EngineMetrics
	Type() EngineType
	// Addr returns the bound listener address, or nil if not yet listening.
	Addr() net.Addr
}

Engine is the interface that all engine implementations must satisfy.

type EngineMetrics

type EngineMetrics struct {
	RequestCount      uint64
	ActiveConnections int64
	ErrorCount        uint64
	Throughput        float64
	LatencyP50        time.Duration
	LatencyP99        time.Duration
	LatencyP999       time.Duration
}

EngineMetrics is a snapshot of engine performance counters. Each engine implementation maintains internal atomic counters and populates a snapshot on Metrics() calls.

type EngineType

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

EngineType identifies which I/O engine implementation is in use.

const (
	IOUring  EngineType = iota // io_uring-based engine
	Epoll                      // epoll-based engine
	Adaptive                   // runtime-adaptive engine selection
	Std                        // net/http stdlib engine
)

I/O engine implementation types.

func (EngineType) String

func (t EngineType) String() string

type Protocol

type Protocol uint8

Protocol represents the HTTP protocol version.

const (
	HTTP1 Protocol = iota // HTTP/1.1
	H2C                   // HTTP/2 cleartext
	Auto                  // auto-negotiate
)

HTTP protocol version constants.

func (Protocol) String

func (p Protocol) String() string

type SwitchFreezer

type SwitchFreezer interface {
	FreezeSwitching()
	UnfreezeSwitching()
}

SwitchFreezer is implemented by the adaptive engine.

type Tier

type Tier uint8

Tier represents an io_uring capability tier. Ordering forms a strict hierarchy suitable for >= comparisons.

const (
	None     Tier = iota // no io_uring support
	Base                 // kernel 5.10+
	Mid                  // kernel 5.13+ (COOP_TASKRUN)
	High                 // kernel 5.19+ (multishot accept/recv, provided buffers)
	Optional             // kernel 6.0+ (SINGLE_ISSUER, SQPOLL)
)

io_uring capability tiers in ascending order of feature availability.

func (Tier) Available

func (t Tier) Available() bool

Available reports whether this tier represents a detected capability.

func (Tier) String

func (t Tier) String() string