eve.backend.common

Shared Layer 0 types used by all OS backends.

This module keeps the vocabulary between platform pollers small and explicit so higher layers can talk about handles, interests, readiness, and translated events without depending on OS-specific constants.

enum AddressFamily BackendId DnsError LimitAction LimitKind Signal
struct BackendCapabilities EventLoopLimits Handle IoInterest IoReady IpAddress OsEvent ResourceUsage
fn backendName

Types 14

enumBackendId : ubyte

Identifies the active Layer 0 backend implementation.

This enum allows higher layers and users to determine which backend is actually being used at runtime, which is important because:

  • Linux may fall back from io_uring to epoll if io_uring setup fails
  • Windows may fall back from IOCP to WSAPoll
  • Different backends have different performance characteristics

Example: 

auto loop = EventLoop.create();
writeln("Using backend: ", loop.backendId);
if (loop.backendId == BackendId.IO_URING) {
    writeln("io_uring is active - optimal performance");
}

UNKNOWN = 0Unknown or uninitialized backend.
IO_URING = 1Linux io_uring (Linux 5.1+, optimal performance).
EPOLL = 2Linux epoll (fallback when io_uring unavailable).
SELECT = 3POSIX select (portable fallback, limited scalability).
IOCP = 4Windows I/O Completion Ports (optimal for Windows).
WSAPOLL = 5Windows WSAPoll (fallback for older Windows or specific scenarios).
KQUEUE = 6BSD/macOS kqueue backend.
POLL = 7POSIX poll (portable fallback, no FD_SETSIZE limit).
structBackendCapabilities

Capability flags reported by a Layer 0 backend.

These flags help higher layers and users understand what features are available on the current platform/backend combination.

Fields
bool supportsIoWatchBackend can watch file descriptors/handles for readiness.
bool supportsNativeTimersBackend can handle timers natively (vs. emulation).
bool supportsSignalsBackend can receive OS signals.
bool supportsCrossThreadWakeupBackend supports cross-thread wakeup notifications.
bool supportsUnixSocketsBackend supports Unix domain sockets (POSIX only).
bool supportsAsyncFilesBackend supports async file I/O without thread pool.
bool supportsHighResTimersBackend supports high-resolution timers (< 1ms).
bool supportsSqpollBackend supports SQPOLL mode (kernel-side submission polling).
bool supportsFixedBuffersBackend supports zero-copy I/O via registered fixed buffers.
bool supportsSpliceBackend supports splice/sendfile operations.
uint maxHandleHintApproximate maximum file descriptors/handles (0 = unknown/unlimited).
bool isFallbackThe backend fell back from a preferred implementation.
int fallbackReasonError code from failed preferred backend setup (0 = no error).
structHandle

Lightweight wrapper around the backend's native handle type.

The wrapper does not own the handle lifetime. It exists so higher layers can avoid passing raw OS primitives directly.

Fields
NativeHandle value
invalidSentinel handle used when a registration has no valid native handle.
Methods
Handle fromNative(NativeHandle value) static pure @safe nothrow @nogcWrap a native OS handle.
bool isValid() @property const pure @safe nothrow @nogcCheck whether the wrapped handle is valid for the current platform.
enumAddressFamily : ubyte

Address families for networking.

This enum is used instead of Phobos' std.socket.AddressFamily to remain strictly @nogc and to keep the vocabulary between OS backends normalized and small.

UNSPEC
IPV4
IPV6
UNIX
structIpAddress

Representation of an IP address.

This struct is used instead of Phobos' std.socket.Address classes to ensure zero-allocation performance and to allow embedding directly into WatcherSlot unions.

Fields
AddressFamily family
Methods
bool isValid() @property const pure @safe nothrow @nogcCheck whether the address is valid (not unspecified).
string toString() const @safeConvert the IP address to its standard string representation.
enumDnsError : int

Common DNS resolution errors.

These error codes correspond to standard DNS resolution failures that may occur during hostname lookup operations.

Retryability and Fatality Guide:

  • OK — Success, no retry needed
  • BAD_FLAGS — Fatal, invalid flags passed to resolver
  • NONAME — Fatal, hostname does not exist
  • AGAIN — Retryable, temporary resolver failure
  • FAIL — Maybe retryable, depends on DNS server state
  • FAMILY — Fatal, address family not supported
  • MEMORY — Maybe retryable, out of memory
  • SYSTEM — Maybe retryable, system-level error occurred
  • OVERFLOW — Fatal, result buffer too small
  • CANCELLED — Fatal, operation was cancelled by user

OK = 0Resolution completed successfully. Retryable: No (operation completed) Fatal: No
BAD_FLAGS = 1Invalid flags passed to resolver. Retryable: No Fatal: Yes (invalid arguments) Action: Fix flags before retrying
NONAME = 2Hostname does not exist. Retryable: No Fatal: Yes (name resolution failed permanently)
AGAIN = 3Temporary failure; retry may succeed. Retryable: Yes (temporary resolver failure) Fatal: No Action: Wait briefly before retrying
FAIL = 4Non-recoverable failure from name server. Retryable: Maybe (depends on DNS server state) Fatal: Depends on cause Action: May succeed with different DNS server or after delay
FAMILY = 5Address family not supported. Retryable: No Fatal: Yes (requested address family unavailable)
MEMORY = 6Out of memory. Retryable: Maybe (if memory becomes available) Fatal: Depends on system state Action: Reduce memory usage before retrying
SYSTEM = 7System-level error occurred. Retryable: Maybe (depends on underlying error) Fatal: Depends on error code Action: Check errno for details
OVERFLOW = 8Result buffer overflow. Retryable: No Fatal: Yes (internal buffer too small) Action: Report as bug if encountered
CANCELLED = 9Operation was cancelled. Retryable: No Fatal: Yes (user requested cancellation)
enumLimitAction : ubyte

Action taken when an EventLoop resource limit is hit.

rejectReturn an error or refuse registration (default).
dropOldestDrop the oldest compatible watcher/connection to make room.
callbackInvoke a user-provided callback to decide.
enumLimitKind : ubyte

Types of resource limits tracked by an EventLoop.

watchersMaximum number of total watchers (I/O, timers, signals, etc.).
sendQueueMaximum total bytes buffered in all TCP send queues.
timersMaximum number of active timers.
fileDescriptorsMaximum number of open file descriptors.
connectionsMaximum number of active TCP/Unix connections.
structEventLoopLimits

Resource limits configuration for an EventLoop.

Fields
uint maxWatchersMaximum number of registered watchers. 0 = unlimited.
size_t maxSendQueueBytesMaximum total bytes in TCP send queues. 0 = unlimited.
uint maxTimersMaximum pending timer count. 0 = unlimited.
uint maxFdsMaximum file descriptors to keep open. 0 = use system limit.
uint maxConnectionsMaximum number of active connections. 0 = unlimited.
LimitAction onLimitHitAction when a limit is hit.
structResourceUsage

Snapshot of current resource usage in an EventLoop.

Fields
size_t watchersTotal number of active watchers.
size_t sendQueueBytesTotal bytes buffered in all send queues.
size_t timersTotal number of active timers.
size_t activeConnectionsTotal number of active network connections.
size_t fileDescriptorsEstimate of total open file descriptors managed by the loop.
size_t iterationCountTotal number of completed loop iterations (runOnce turns).
size_t wakeupCountTotal number of cross-thread wakeup notifications triggered.
size_t errorCountTotal number of backend errors or silently ignored failures.
size_t limitRejectionCountTotal number of registrations rejected due to a configured limit.
enumSignal : ubyte

Normalized signal values that higher layers may care about.

INTERRUPT
TERMINATE
HANGUP
CHILD
USER1
USER2
WINCHWindow size change (POSIX only).
structIoInterest

Requested I/O interests.

Instances behave like a small bit-mask value that can be combined with `|` and tested with contains.

Fields
ushort bits
noneNo readiness requested.
readableReadability requested.
writableWritability requested.
priorityExceptional or priority data requested.
errorError notifications requested.
hangupHangup notifications requested.
Methods
bool contains(IoInterest other) const pure @safe nothrow @nogcCheck whether all bits from `other` are present.
IoInterest opBinary(string op : "|")(IoInterest other) const pure @safe nothrow @nogcCombine two interest masks.
IoInterest opBinary(string op : "&")(IoInterest other) const pure @safe nothrow @nogcIntersect two interest masks.
IoInterest opBinary(string op : "^")(IoInterest other) const pure @safe nothrow @nogcToggle bits from another interest mask.
void opOpAssign(string op : "|")(IoInterest other) pure @safe nothrow @nogcAdd interest bits in place.
void opOpAssign(string op : "&")(IoInterest other) pure @safe nothrow @nogcKeep only intersecting interest bits in place.
void opOpAssign(string op : "^")(IoInterest other) pure @safe nothrow @nogcToggle interest bits in place.
bool opCast(T : bool)() const pure @safe nothrow @nogcConvert the interest mask to a boolean.
structIoReady

Actual readiness reported by the OS backend.

Fields
ushort bits
noneNo readiness reported.
readableReadability reported.
writableWritability reported.
priorityExceptional or priority data reported.
errorError state reported.
hangupHangup or peer shutdown reported.
Methods
bool contains(IoReady other) const pure @safe nothrow @nogcCheck whether all bits from `other` are present.
IoReady opBinary(string op : "|")(IoReady other) const pure @safe nothrow @nogcCombine two readiness masks.
IoReady opBinary(string op : "&")(IoReady other) const pure @safe nothrow @nogcIntersect two readiness masks.
IoReady opBinary(string op : "^")(IoReady other) const pure @safe nothrow @nogcToggle bits from another readiness mask.
void opOpAssign(string op : "|")(IoReady other) pure @safe nothrow @nogcAdd readiness bits in place.
void opOpAssign(string op : "&")(IoReady other) pure @safe nothrow @nogcKeep only intersecting readiness bits in place.
void opOpAssign(string op : "^")(IoReady other) pure @safe nothrow @nogcToggle readiness bits in place.
bool opCast(T : bool)() const pure @safe nothrow @nogcConvert the readiness mask to a boolean.
structOsEvent

Shared event payload emitted by Layer 0 backends.

Fields
ulong userDataOpaque user value attached during backend registration.
IoReady readyNormalized readiness flags translated from the native backend event.

Functions 1

fnstring backendName(BackendId id) pure @safe nothrow @nogcReturns a human-readable name for a backend.