Documentation
¶
Overview ¶
Package engine defines the core Engine interface and associated types used by all I/O engine implementations (io_uring, epoll, adaptive, std).
This package is the dependency root for engine-related types. User code typically interacts with engines through the top-level celeris package rather than importing this package directly.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AcceptController ¶ added in v0.3.0
type AcceptController interface {
// PauseAccept stops accepting new connections. Existing connections continue.
PauseAccept() error
// ResumeAccept resumes accepting new connections after a pause.
ResumeAccept() error
}
AcceptController is implemented by engines that support dynamic accept control, used by the adaptive engine to pause/resume individual sub-engines during switches.
type CapabilityProfile ¶
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
}
CapabilityProfile describes the I/O capabilities detected on the current system. The probe package populates this at startup to guide engine selection.
func NewDefaultProfile ¶
func NewDefaultProfile() CapabilityProfile
NewDefaultProfile returns a CapabilityProfile with safe defaults.
type Engine ¶
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
}
Engine is the interface that all I/O engine implementations must satisfy. Implementations include io_uring, epoll, adaptive, and the standard library net/http server. Engine methods are safe for concurrent use after Listen is called.
type EngineMetrics ¶
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
}
EngineMetrics is a point-in-time snapshot of engine-level performance counters. Each engine maintains internal atomic counters and populates a fresh snapshot on each [Engine.Metrics] call.
type EngineType ¶
type EngineType uint8 //nolint:revive // user-approved name
EngineType identifies which I/O engine implementation is in use.
const ( IOUring EngineType // io_uring-based engine Epoll // epoll-based engine Adaptive // runtime-adaptive engine selection Std // net/http stdlib engine )
I/O engine implementation types. The zero value is engineDefault which resolves to Adaptive on Linux and Std elsewhere (see resource.Config.WithDefaults).
func (EngineType) IsDefault ¶ added in v1.1.0
func (t EngineType) IsDefault() bool
IsDefault reports whether the engine type is the unset zero value.
func (EngineType) String ¶
func (t EngineType) String() string
String returns the human-readable engine type name (e.g. "io_uring", "epoll").
type Protocol ¶
type Protocol uint8
Protocol represents the HTTP protocol version.
const ( HTTP1 Protocol // HTTP/1.1 H2C // HTTP/2 cleartext Auto // auto-negotiate )
HTTP protocol version constants. The zero value is protocolDefault which resolves to Auto (see resource.Config.WithDefaults).
type SwitchFreezer ¶ added in v0.3.0
type SwitchFreezer interface {
// FreezeSwitching prevents the adaptive engine from switching.
FreezeSwitching()
// UnfreezeSwitching allows engine switching to resume.
UnfreezeSwitching()
}
SwitchFreezer is implemented by the adaptive engine to allow external code (e.g., benchmarks) to temporarily prevent engine switches.
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package epoll implements the epoll-based I/O engine for Linux.
|
Package epoll implements the epoll-based I/O engine for Linux. |
|
Package iouring implements an engine backed by Linux io_uring.
|
Package iouring implements an engine backed by Linux io_uring. |
|
Package std provides an engine implementation backed by net/http.
|
Package std provides an engine implementation backed by net/http. |