Module epoll 

Epoll runtime implementation for WASIX.

This module centralizes epoll internals behind a small crate-internal API used by epoll_create, epoll_ctl, and epoll_wait.

Architecture

The implementation uses:

• EpollState: global state for one epoll fd (subscriptions, ready queue, notifier).
• EpollSubState: per-watched-fd state (pending_bits, enqueued, generation, metadata).
• EpollHandler: producer-side interest handler attached to socket/pipe/notification sources.

Important flows

Registration (epoll_ctl ADD/MOD/DEL)

1. epoll_ctl creates/removes EpollSubState entries in EpollState.subscriptions.
2. On ADD/MOD, register_epoll_handler() installs an EpollHandler on the target fd.
3. Guard ownership is stored in EpollSubState.joins; dropping a subscription drops guards and unregisters handlers.

Producer path (EpollHandler::push_interest)

1. Convert InterestType to a readiness bit.
2. Set pending_bits atomically.
3. Enqueue exactly one ReadyItem per subscription while enqueued == true.
4. Wake one waiter via Notify.

Consumer path (drain_ready_events used by epoll_wait)

1. Pop ReadyItem from the ready queue.
2. Resolve the current subscription and drop stale/missing entries.
3. Atomically take readiness bits, clear enqueued, and map bits to output events.
4. Repair queue state if a race set new bits during draining.

Correctness model

• pending_bits is the source of truth for unread readiness.
• enqueued deduplicates queue presence per subscription.
• generation prevents stale queued entries from emitting after DEL/MOD.
• Consumer logic tolerates stale queue entries and must never await while holding locks.

Structs

EpollFd

EpollHandler 🔒

EpollJoinGuard

EpollState

EpollSubState

ReadyItem 🔒

Constants

ERR_BIT 🔒

HUP_BIT 🔒

READABLE_BIT 🔒

WRITABLE_BIT 🔒

Statics

EPOLL_EMPTY_DEQUEUE_ENTRIES 🔒

EPOLL_ENQUEUE_ATTEMPTS 🔒

EPOLL_ENQUEUE_DEDUPE_HITS 🔒

EPOLL_STALE_GENERATION_DROPS 🔒

Functions

drain_ready_events 🔒

Drains ready items into (EpollFd, readiness) events up to maxevents.

epoll_empty_dequeue_entry 🔒

Increments empty dequeue metric.

epoll_mask_to_pending_bits 🔒

epoll_stale_generation_drop 🔒

Increments stale-generation dequeue metric.

epoll_type_to_pending_bit 🔒

Maps epoll readiness flags into internal pending-bit positions.

interest_to_pending_bit 🔒

Maps a source interest callback variant into the internal pending-bit mask.

pending_bits_to_events 🔒

Converts consumed pending bits into caller-visible epoll events.

prime_immediate_writable_if_applicable 🔒

register_epoll_handler 🔒

Registers an epoll interest handler on the watched fd and returns a guard.

repair_ready_queue_after_drain 🔒

Re-enqueues a subscription if new pending bits arrived during/after consumer drain.