winloop 0.2.0 → 0.2.1

data/ext/winloop/winloop.c

@@ -1,712 +0,0 @@
-/*
- * winloop — a Windows IOCP event-loop backend for a Ruby Fiber Scheduler.
- *
- * This C extension owns one I/O Completion Port plus one \Device\Afd handle and
- * exposes the minimum the Ruby scheduler needs:
- *
- *   Winloop::Backend.new          -> create the IOCP + AFD handle
- *   #poll(io, events)  -> id      arm a one-shot AFD readiness poll for `io`
- *   #cancel(id)                   cancel a pending poll (CancelIoEx)
- *   #wait(timeout_ms)  -> [[id, ready_events], ...]   reap completions (one GQCSEx)
- *   #wakeup                       PostQueuedCompletionStatus (break the wait)
- *   #shutdown                     cancel + drain + close (idempotent)
- *
- * Readiness over a *completion* port is done the libuv/mio/wepoll way: submit
- * IOCTL_AFD_POLL on \Device\Afd as an overlapped op whose ApcContext is the
- * OVERLAPPED pointer (THE make-or-break detail — without it no completion packet
- * is queued). Each in-flight poll is a winloop_req whose OVERLAPPED is the first
- * member, so a completion's lpOverlapped casts straight back to the request.
- *
- * Pure C (no C++/-EHsc), so rb_raise (longjmp) is the normal, safe mechanism.
- * include <ruby.h> before the Windows headers; never name a variable IN/OUT.
- */
-
-#include <ruby.h>
-#include <ruby/io.h>
-#include <ruby/win32.h>
-#include <ruby/st.h>
-#include <ruby/thread.h>
-
-#include <winsock2.h>
-#include <ws2tcpip.h>
-#include <windows.h>
-#include <winternl.h>
-#include <stdint.h>
-
-/* ---- Ruby IO event bits (verified: READABLE=1, WRITABLE=4, PRIORITY=2) ---- */
-#define RB_READABLE 1
-#define RB_PRIORITY 2
-#define RB_WRITABLE 4
-
-/* ---- AFD poll flags / IOCTL (verified on the target machine) ---- */
-#define AFD_POLL_RECEIVE           0x0001
-#define AFD_POLL_RECEIVE_EXPEDITED 0x0002
-#define AFD_POLL_SEND              0x0004
-#define AFD_POLL_DISCONNECT        0x0008
-#define AFD_POLL_ABORT             0x0010
-#define AFD_POLL_LOCAL_CLOSE       0x0020
-#define AFD_POLL_ACCEPT            0x0080
-#define AFD_POLL_CONNECT_FAIL      0x0100
-#define IOCTL_AFD_POLL             0x00012024
-#ifndef SIO_BASE_HANDLE
-#define SIO_BASE_HANDLE            0x48000022
-#endif
-#ifndef STATUS_PENDING
-#define STATUS_PENDING ((NTSTATUS)0x00000103L)
-#endif
-#define AFD_FILE_OPEN 0x00000001
-
-#define WAKE_KEY ((ULONG_PTR)0x57414B45ull) /* "WAKE" — PostQueuedCompletionStatus marker */
-#define AFD_KEY  ((ULONG_PTR)0x41464430ull) /* "AFD0" — the AFD handle's completion key */
-#define EXT_KEY  ((ULONG_PTR)0x45585431ull) /* "EXT1" — ALL generic client ops (winloop 0.2) */
-#define REAP_CAP 64
-
-/* Generic op state machine: prepare -> submit -> complete (reaped) -> retire (freed).
- * Only a reaped completion ends kernel ownership of the OVERLAPPED + buffer; the
- * sole exception is op_abandon on a PREPARED op the kernel never saw. */
-enum { OP_PREPARED = 0, OP_SUBMITTED = 1, OP_COMPLETED = 2 };
-
-typedef struct _AFD_POLL_HANDLE_INFO {
-    HANDLE   Handle;
-    ULONG    Events;
-    NTSTATUS Status;
-} AFD_POLL_HANDLE_INFO;
-typedef struct _AFD_POLL_INFO {
-    LARGE_INTEGER        Timeout;
-    ULONG                NumberOfHandles;
-    ULONG                Exclusive;
-    AFD_POLL_HANDLE_INFO Handles[1];
-} AFD_POLL_INFO;
-
-typedef NTSTATUS (NTAPI *PFN_NtCreateFile)(PHANDLE, ACCESS_MASK, POBJECT_ATTRIBUTES,
-    PIO_STATUS_BLOCK, PLARGE_INTEGER, ULONG, ULONG, ULONG, ULONG, PVOID, ULONG);
-typedef NTSTATUS (NTAPI *PFN_NtDeviceIoControlFile)(HANDLE, HANDLE, PIO_APC_ROUTINE,
-    PVOID, PIO_STATUS_BLOCK, ULONG, PVOID, ULONG, PVOID, ULONG);
-typedef VOID (NTAPI *PFN_RtlInitUnicodeString)(PUNICODE_STRING, PCWSTR);
-typedef ULONG (NTAPI *PFN_RtlNtStatusToDosError)(NTSTATUS);
-
-static PFN_NtCreateFile           pNtCreateFile;
-static PFN_NtDeviceIoControlFile  pNtDeviceIoControlFile;
-static PFN_RtlInitUnicodeString   pRtlInitUnicodeString;
-static PFN_RtlNtStatusToDosError  pRtlNtStatusToDosError;
-
-#ifndef InitializeObjectAttributes
-#define InitializeObjectAttributes(p, n, a, r, s) do { \
-    (p)->Length = sizeof(OBJECT_ATTRIBUTES); (p)->RootDirectory = (r); \
-    (p)->Attributes = (a); (p)->ObjectName = (n); (p)->SecurityDescriptor = (s); \
-    (p)->SecurityQualityOfService = NULL; } while (0)
-#endif
-
-/* One in-flight AFD poll. OVERLAPPED MUST be first so lpOverlapped casts back. */
-typedef struct {
-    OVERLAPPED    ov;
-    uint64_t      id;
-    AFD_POLL_INFO in;
-    AFD_POLL_INFO out;
-} winloop_req;
-
-/* One generic op (winloop 0.2). OVERLAPPED MUST be first: a completion's
- * lpOverlapped casts back to the record — the same proven pattern as winloop_req. */
-typedef struct {
-    OVERLAPPED ov;        /* zeroed at prepare; kernel writes Internal/InternalHigh   */
-    uint64_t   id;        /* Ruby-visible op id (shares next_id with AFD reqs)        */
-    uint64_t   tag;       /* user value, echoed in the completion tuple               */
-    HANDLE     handle;    /* associated client handle for CancelIoEx; never NULL      */
-    int        state;     /* OP_PREPARED -> OP_SUBMITTED -> OP_COMPLETED              */
-    DWORD      bytes;     /* filled at reap                                           */
-    DWORD      error;     /* Win32 code at reap (RtlNtStatusToDosError(ov.Internal))  */
-    size_t     cap;       /* embedded buffer capacity (0 = none)                      */
-    /* unsigned char buf[cap] co-allocated at OP_BUF_OFFSET (8-byte aligned)          */
-} winloop_op;
-
-#define OP_BUF_OFFSET ((sizeof(winloop_op) + 7) & ~(size_t)7)
-
-typedef struct {
-    HANDLE     iocp;
-    HANDLE     afd;
-    uint64_t   next_id;
-    st_table  *reqs;          /* id -> winloop_req* */
-    st_table  *ops_by_id;     /* id -> winloop_op*  (Ruby-facing op methods)          */
-    st_table  *ops_by_addr;   /* OVERLAPPED addr -> winloop_op* (defensive reap)      */
-    st_table  *assoc_handles; /* set of HANDLE values passed to #associate (op_prepare
-                                 validation ONLY — never used for blanket cancels, so
-                                 a recycled handle value can't trigger a wrong cancel) */
-    size_t     op_bytes;      /* live op allocations, reported by backend_memsize     */
-    int        closed;
-} winloop_backend;
-
-static VALUE mWinloop, cBackend, eError;
-
-/* ---- ntdll resolution ---- */
-static int resolve_ntdll(void) {
-    HMODULE nt = GetModuleHandleW(L"ntdll.dll");
-    if (!nt) return 0;
-    pNtCreateFile          = (PFN_NtCreateFile)          GetProcAddress(nt, "NtCreateFile");
-    pNtDeviceIoControlFile = (PFN_NtDeviceIoControlFile) GetProcAddress(nt, "NtDeviceIoControlFile");
-    pRtlInitUnicodeString  = (PFN_RtlInitUnicodeString)  GetProcAddress(nt, "RtlInitUnicodeString");
-    pRtlNtStatusToDosError = (PFN_RtlNtStatusToDosError) GetProcAddress(nt, "RtlNtStatusToDosError");
-    return pNtCreateFile && pNtDeviceIoControlFile && pRtlInitUnicodeString &&
-           pRtlNtStatusToDosError;
-}
-
-static HANDLE afd_open(void) {
-    HANDLE h = INVALID_HANDLE_VALUE;
-    UNICODE_STRING name; OBJECT_ATTRIBUTES oa; IO_STATUS_BLOCK iosb; NTSTATUS st;
-    pRtlInitUnicodeString(&name, L"\\Device\\Afd\\Winloop");
-    InitializeObjectAttributes(&oa, &name, 0, NULL, NULL);
-    st = pNtCreateFile(&h, SYNCHRONIZE | FILE_READ_DATA | FILE_WRITE_DATA, &oa, &iosb,
-                       NULL, 0, FILE_SHARE_READ | FILE_SHARE_WRITE, AFD_FILE_OPEN, 0, NULL, 0);
-    return (st == 0) ? h : INVALID_HANDLE_VALUE;
-}
-
-static SOCKET base_socket(SOCKET s) {
-    SOCKET base = INVALID_SOCKET; DWORD bytes = 0;
-    if (WSAIoctl(s, SIO_BASE_HANDLE, NULL, 0, &base, sizeof(base), &bytes, NULL, NULL) == 0)
-        return base;
-    return s;
-}
-
-static ULONG ruby_to_afd(int events) {
-    ULONG a = AFD_POLL_ABORT | AFD_POLL_CONNECT_FAIL | AFD_POLL_LOCAL_CLOSE; /* always report errors */
-    if (events & RB_READABLE) a |= AFD_POLL_RECEIVE | AFD_POLL_ACCEPT | AFD_POLL_DISCONNECT;
-    if (events & RB_PRIORITY) a |= AFD_POLL_RECEIVE_EXPEDITED;
-    if (events & RB_WRITABLE) a |= AFD_POLL_SEND;
-    return a;
-}
-
-static int afd_to_ruby(ULONG a) {
-    int e = 0;
-    if (a & (AFD_POLL_RECEIVE | AFD_POLL_RECEIVE_EXPEDITED | AFD_POLL_ACCEPT |
-             AFD_POLL_DISCONNECT | AFD_POLL_LOCAL_CLOSE)) e |= RB_READABLE;
-    if (a & AFD_POLL_RECEIVE_EXPEDITED) e |= RB_PRIORITY;
-    if (a & (AFD_POLL_SEND | AFD_POLL_CONNECT_FAIL)) e |= RB_WRITABLE;
-    /* On abort/error, wake for both directions so the follow-up recv/send surfaces it. */
-    if (a & (AFD_POLL_ABORT | AFD_POLL_CONNECT_FAIL)) e |= RB_READABLE | RB_WRITABLE;
-    return e;
-}
-
-/* ---- TypedData ---- */
-static int free_req_i(st_data_t key, st_data_t val, st_data_t arg) {
-    (void)key; (void)arg;
-    xfree((void *)val);
-    return ST_CONTINUE;
-}
-/* Shutdown sweep step 1: cancel every still-SUBMITTED generic op, per op
- * (CancelIoEx(handle, ov) — precise; a blanket per-handle cancel would be exposed
- * to the recycled-handle-value hazard if a client closed a handle early). */
-static int cancel_submitted_op_i(st_data_t key, st_data_t val, st_data_t arg) {
-    winloop_op *op = (winloop_op *)val;
-    (void)key; (void)arg;
-    if (op->state == OP_SUBMITTED) CancelIoEx(op->handle, &op->ov);
-    /* failures ignored: ERROR_NOT_FOUND = already completed; a (contract-
-     * violating) closed handle simply fails the lookup */
-    return ST_CONTINUE;
-}
-static int count_submitted_op_i(st_data_t key, st_data_t val, st_data_t arg) {
-    winloop_op *op = (winloop_op *)val;
-    (void)key;
-    if (op->state == OP_SUBMITTED) (*(size_t *)arg)++;
-    return ST_CONTINUE;
-}
-/* Shutdown sweep step 4: free every op the kernel can no longer touch. Ops still
- * OP_SUBMITTED (their packet never surfaced inside the bounded drain) are
- * DELIBERATELY LEAKED — the kernel may still write their OVERLAPPED/IOSB, and a
- * use-after-free beats a bounded leak (the libuv tradeoff). In practice the
- * per-op CancelIoEx + the 100 ms drain retires them. */
-static int free_op_unless_submitted_i(st_data_t key, st_data_t val, st_data_t arg) {
-    winloop_op *op = (winloop_op *)val;
-    (void)key; (void)arg;
-    if (op->state != OP_SUBMITTED) xfree(op);
-    return ST_CONTINUE;
-}
-/* During the shutdown drain, mark reaped EXT packets' ops OP_COMPLETED so the
- * sweep may free them. Pure C — also runs from the GC free hook (no Ruby calls). */
-static void drain_mark_ext(winloop_backend *b, OVERLAPPED_ENTRY *ents, ULONG n) {
-    ULONG i;
-    for (i = 0; i < n; i++) {
-        st_data_t val;
-        if (ents[i].lpCompletionKey != EXT_KEY || ents[i].lpOverlapped == NULL) continue;
-        if (!st_lookup(b->ops_by_addr, (st_data_t)(uintptr_t)ents[i].lpOverlapped, &val)) continue;
-        ((winloop_op *)val)->state = OP_COMPLETED;
-    }
-}
-static void backend_drain_and_close(winloop_backend *b) {
-    if (b->closed) return;
-    b->closed = 1;
-    if (b->reqs) {
-        /* Cancel everything still pending so the kernel stops owning our OVERLAPPEDs. */
-        if (b->afd != INVALID_HANDLE_VALUE) CancelIoEx(b->afd, NULL);
-    }
-    if (b->ops_by_id) st_foreach(b->ops_by_id, cancel_submitted_op_i, 0);
-    /* Drain queued completions (best-effort) so no packet references freed memory. */
-    if (b->iocp) {
-        OVERLAPPED_ENTRY ents[REAP_CAP]; ULONG n = 0; int spins = 0;
-        while (GetQueuedCompletionStatusEx(b->iocp, ents, REAP_CAP, &n, 0, FALSE) && n && spins++ < 4096) {
-            if (b->ops_by_addr) drain_mark_ext(b, ents, n);
-        }
-        /* One bounded 100 ms drain — ONLY when generic ops are still in flight
-         * (their cancel completions are usually instants away). Existing AFD-only
-         * workloads never take this branch; the GVL stays held (this also runs
-         * from the GC free hook, where releasing the GVL is not an option). */
-        if (b->ops_by_id) {
-            size_t still = 0;
-            st_foreach(b->ops_by_id, count_submitted_op_i, (st_data_t)&still);
-            if (still &&
-                GetQueuedCompletionStatusEx(b->iocp, ents, REAP_CAP, &n, 100, FALSE) && n) {
-                drain_mark_ext(b, ents, n);
-                spins = 0;
-                while (GetQueuedCompletionStatusEx(b->iocp, ents, REAP_CAP, &n, 0, FALSE) && n && spins++ < 4096)
-                    drain_mark_ext(b, ents, n);
-            }
-        }
-    }
-    if (b->afd != INVALID_HANDLE_VALUE) { CloseHandle(b->afd); b->afd = INVALID_HANDLE_VALUE; }
-    if (b->iocp) { CloseHandle(b->iocp); b->iocp = NULL; }
-    if (b->reqs) { st_foreach(b->reqs, free_req_i, 0); st_free_table(b->reqs); b->reqs = NULL; }
-    if (b->ops_by_id) { st_foreach(b->ops_by_id, free_op_unless_submitted_i, 0); st_free_table(b->ops_by_id); b->ops_by_id = NULL; }
-    if (b->ops_by_addr) { st_free_table(b->ops_by_addr); b->ops_by_addr = NULL; }
-    if (b->assoc_handles) { st_free_table(b->assoc_handles); b->assoc_handles = NULL; }
-    b->op_bytes = 0;
-}
-static void backend_free(void *p) {
-    winloop_backend *b = (winloop_backend *)p;
-    if (!b) return;
-    backend_drain_and_close(b);
-    xfree(b);
-}
-static size_t backend_memsize(const void *p) {
-    const winloop_backend *b = (const winloop_backend *)p;
-    return sizeof(winloop_backend) + (b ? b->op_bytes : 0);
-}
-static const rb_data_type_t backend_type = {
-    "Winloop::Backend", { 0, backend_free, backend_memsize }, 0, 0, RUBY_TYPED_FREE_IMMEDIATELY
-};
-
-static winloop_backend *get_backend(VALUE self) {
-    winloop_backend *b;
-    TypedData_Get_Struct(self, winloop_backend, &backend_type, b);
-    if (!b || b->closed) rb_raise(eError, "winloop: backend is closed");
-    return b;
-}
-
-/* The op methods additionally need the op tables, which only #initialize creates
- * (a Backend.allocate'd-but-never-initialized object must raise, not crash). */
-static winloop_backend *get_backend_ops(VALUE self) {
-    winloop_backend *b = get_backend(self);
-    if (!b->ops_by_id) rb_raise(eError, "winloop: backend is closed");
-    return b;
-}
-
-static VALUE backend_alloc(VALUE klass) {
-    winloop_backend *b;
-    VALUE obj = TypedData_Make_Struct(klass, winloop_backend, &backend_type, b);
-    b->afd = INVALID_HANDLE_VALUE;
-    return obj;
-}
-
-static VALUE backend_initialize(VALUE self) {
-    winloop_backend *b;
-    TypedData_Get_Struct(self, winloop_backend, &backend_type, b);
-    if (!resolve_ntdll()) rb_raise(eError, "winloop: could not resolve ntdll entry points");
-    b->iocp = CreateIoCompletionPort(INVALID_HANDLE_VALUE, NULL, 0, 0);
-    if (!b->iocp) rb_raise(eError, "winloop: CreateIoCompletionPort failed (%lu)", GetLastError());
-    b->afd = afd_open();
-    if (b->afd == INVALID_HANDLE_VALUE) {
-        CloseHandle(b->iocp); b->iocp = NULL;
-        rb_raise(eError, "winloop: could not open \\Device\\Afd (unsupported platform?)");
-    }
-    if (!CreateIoCompletionPort(b->afd, b->iocp, AFD_KEY, 0)) {
-        CloseHandle(b->afd); CloseHandle(b->iocp); b->afd = INVALID_HANDLE_VALUE; b->iocp = NULL;
-        rb_raise(eError, "winloop: could not associate AFD handle (%lu)", GetLastError());
-    }
-    b->next_id = 0;
-    b->reqs = st_init_numtable();
-    /* st_data_t is pointer-sized; numtables hold ids/addresses/handles arm64-clean. */
-    b->ops_by_id     = st_init_numtable();
-    b->ops_by_addr   = st_init_numtable();
-    b->assoc_handles = st_init_numtable();
-    b->op_bytes = 0;
-    b->closed = 0;
-    return self;
-}
-
-/* Arm a one-shot readiness poll on `io` for `events`; returns the request id. */
-static VALUE backend_poll(VALUE self, VALUE io, VALUE vevents) {
-    winloop_backend *b = get_backend(self);
-    int events = NUM2INT(vevents);
-    int fd = rb_io_descriptor(io);
-    SOCKET sock = rb_w32_get_osfhandle(fd);
-    if (sock == INVALID_SOCKET || !rb_w32_is_socket(fd))
-        rb_raise(eError, "winloop: fd %d is not a socket (winloop polls sockets)", fd);
-    SOCKET base = base_socket(sock);
-
-    winloop_req *req = ALLOC(winloop_req);
-    memset(req, 0, sizeof(*req));
-    req->id = ++b->next_id;
-    req->in.Timeout.QuadPart = INT64_MAX; /* stays pending until an event fires */
-    req->in.NumberOfHandles = 1;
-    req->in.Exclusive = FALSE;
-    req->in.Handles[0].Handle = (HANDLE)base;
-    req->in.Handles[0].Events = ruby_to_afd(events);
-
-    NTSTATUS st = pNtDeviceIoControlFile(b->afd, NULL, NULL, &req->ov,
-        (PIO_STATUS_BLOCK)&req->ov.Internal, IOCTL_AFD_POLL,
-        &req->in, sizeof(req->in), &req->out, sizeof(req->out));
-    if (st != STATUS_PENDING && st != 0 /*STATUS_SUCCESS*/) {
-        xfree(req);
-        rb_raise(eError, "winloop: AFD poll failed (status 0x%08lX)", (unsigned long)st);
-    }
-    /* STATUS_SUCCESS == satisfied synchronously, but a completion packet is still
-       queued (we never set FILE_SKIP_COMPLETION_PORT_ON_SUCCESS) — handle uniformly. */
-    st_insert(b->reqs, (st_data_t)req->id, (st_data_t)req);
-    return ULL2NUM(req->id);
-}
-
-/* Cancel a pending poll. The cancelled op still posts a (STATUS_CANCELLED)
-   completion, which #wait reaps and frees — so we do NOT free here. */
-static VALUE backend_cancel(VALUE self, VALUE vid) {
-    winloop_backend *b = get_backend(self);
-    uint64_t id = NUM2ULL(vid);
-    st_data_t val;
-    if (st_lookup(b->reqs, (st_data_t)id, &val)) {
-        winloop_req *req = (winloop_req *)val;
-        CancelIoEx(b->afd, &req->ov);
-    }
-    return Qnil;
-}
-
-/* ===== Generic OVERLAPPED ops — "bring your own OVERLAPPED" (winloop 0.2) =====
- *
- * The whole feature is Integer-in/Integer-out: handles, addresses and ids cross
- * the API as Ruby Integers (the cross-gem ABI — other gems never link winloop).
- * winloop owns op memory (OVERLAPPED + embedded buffer, one heap allocation);
- * clients own their handles — winloop NEVER calls CloseHandle on them. */
-
-static const char *op_state_name(int state) {
-    switch (state) {
-      case OP_PREPARED:  return "prepared";
-      case OP_SUBMITTED: return "submitted";
-      default:           return "completed";
-    }
-}
-
-static winloop_op *op_lookup(winloop_backend *b, uint64_t id) {
-    st_data_t val;
-    if (!st_lookup(b->ops_by_id, (st_data_t)id, &val))
-        rb_raise(eError, "winloop: unknown op id %llu", (unsigned long long)id);
-    return (winloop_op *)val;
-}
-
-/* Remove an op from both tables and free it (the ONLY free path besides the
- * shutdown sweep). Callers must have established the kernel no longer owns it. */
-static void op_retire(winloop_backend *b, winloop_op *op) {
-    st_data_t key = (st_data_t)op->id;
-    st_delete(b->ops_by_id, &key, NULL);
-    key = (st_data_t)(uintptr_t)&op->ov;
-    st_delete(b->ops_by_addr, &key, NULL);
-    b->op_bytes -= OP_BUF_OFFSET + op->cap;
-    xfree(op);
-}
-
-/* Associate `handle` (opened FILE_FLAG_OVERLAPPED) with the backend's IOCP under
- * EXT_KEY. Permanent for the handle's lifetime (Win32: one port per handle, no
- * disassociation); the caller keeps ownership. */
-static VALUE backend_associate(VALUE self, VALUE vhandle) {
-    winloop_backend *b = get_backend_ops(self);
-    uint64_t hv = NUM2ULL(vhandle); /* coercion first: a raise here owns nothing */
-    DWORD gle;
-    if (hv == 0 || hv == UINT64_MAX)
-        rb_raise(rb_eArgError, "winloop: %llu is not a usable HANDLE value",
-                 (unsigned long long)hv);
-    if (!CreateIoCompletionPort((HANDLE)(uintptr_t)hv, b->iocp, EXT_KEY, 0)) {
-        gle = GetLastError(); /* captured before any Ruby allocation */
-        rb_raise(eError, "winloop: could not associate handle %llu with the completion "
-                 "port (error %lu: already associated with a completion port, or not "
-                 "opened with FILE_FLAG_OVERLAPPED)", (unsigned long long)hv, gle);
-    }
-    st_insert(b->assoc_handles, (st_data_t)hv, (st_data_t)1);
-    return Qtrue;
-}
-
-/* Private primitive behind Winloop::Backend#op_prepare (lib/winloop/ops.rb owns
- * the kwargs + range validation). Allocates one op record: zeroed OVERLAPPED +
- * tag + optional embedded buffer; returns [op_id, ov_addr, buf_addr]. */
-static VALUE backend__op_prepare(VALUE self, VALUE vhandle, VALUE vtag, VALUE vcap) {
-    winloop_backend *b = get_backend_ops(self);
-    /* All coercion before any allocation (raise hygiene). */
-    uint64_t hv  = NUM2ULL(vhandle);
-    uint64_t tag = NUM2ULL(vtag);
-    uint64_t cap = NUM2ULL(vcap);
-    size_t total;
-    winloop_op *op;
-    if (cap > 16ull * 1024 * 1024) /* defensive twin of OP_CAPACITY_MAX (send bypass) */
-        rb_raise(rb_eArgError, "winloop: capacity %llu exceeds OP_CAPACITY_MAX",
-                 (unsigned long long)cap);
-    /* The anti-hang check (§3.4 rule 8): an op on a handle that is not on the
-     * port never completes — not an error, a silent loop freeze. Honestly: a
-     * handle that was associated, closed and recycled to the same value passes. */
-    if (!st_lookup(b->assoc_handles, (st_data_t)hv, NULL))
-        rb_raise(eError, "winloop: handle %llu was never associated with this backend "
-                 "— call #associate first", (unsigned long long)hv);
-
-    total = OP_BUF_OFFSET + (size_t)cap;
-    op = (winloop_op *)xmalloc(total); /* a raise above this line leaks nothing */
-    memset(op, 0, total); /* zeroed OVERLAPPED (offset 0 reads); buffer never leaks heap */
-    op->id     = ++b->next_id;
-    op->tag    = tag;
-    op->handle = (HANDLE)(uintptr_t)hv;
-    op->state  = OP_PREPARED;
-    op->cap    = (size_t)cap;
-    st_insert(b->ops_by_id, (st_data_t)op->id, (st_data_t)op);
-    /* An OOM longjmp from this second insert leaks one record until the shutdown
-     * sweep — the identical, accepted exposure as backend_poll's st_insert. */
-    st_insert(b->ops_by_addr, (st_data_t)(uintptr_t)&op->ov, (st_data_t)op);
-    b->op_bytes += total;
-    return rb_ary_new_from_args(3, ULL2NUM(op->id), ULL2NUM((uintptr_t)&op->ov),
-                                cap ? ULL2NUM((uintptr_t)((char *)op + OP_BUF_OFFSET))
-                                    : ULL2NUM(0));
-}
-
-/* Call after the client's native call returned success OR ERROR_IO_PENDING —
- * both queue exactly one completion packet (no skip-on-success, ever). */
-static VALUE backend_op_submitted(VALUE self, VALUE vid) {
-    winloop_backend *b = get_backend_ops(self);
-    winloop_op *op = op_lookup(b, NUM2ULL(vid));
-    if (op->state != OP_PREPARED)
-        rb_raise(eError, "winloop: op %llu is %s; op_submitted is only legal on a "
-                 "prepared op", (unsigned long long)op->id, op_state_name(op->state));
-    op->state = OP_SUBMITTED;
-    return Qtrue;
-}
-
-/* For a native call that failed SYNCHRONOUSLY (GetLastError != ERROR_IO_PENDING):
- * the kernel never saw the op, no packet will ever arrive — free immediately. */
-static VALUE backend_op_abandon(VALUE self, VALUE vid) {
-    winloop_backend *b = get_backend_ops(self);
-    winloop_op *op = op_lookup(b, NUM2ULL(vid));
-    if (op->state == OP_SUBMITTED)
-        rb_raise(eError, "winloop: op %llu is submitted; a submitted op is retired by "
-                 "its completion, not op_abandon", (unsigned long long)op->id);
-    if (op->state == OP_COMPLETED)
-        rb_raise(eError, "winloop: op %llu is completed; retire it with op_result or "
-                 "op_free, not op_abandon", (unsigned long long)op->id);
-    op_retire(b, op);
-    return Qtrue;
-}
-
-/* CancelIoEx(handle, ov) — targeted, cross-thread-safe. NEVER frees: a cancelled
- * op still posts a packet (usually error 995) which #wait reaps. Returns true if
- * a cancel was issued; false on ERROR_NOT_FOUND (already completed — benign) or
- * ANY other CancelIoEx failure (rb_warn'ed, never raised: await_op's ensure path
- * must never mask an in-flight Timeout/Fiber#raise unwind with a Winloop::Error). */
-static VALUE backend_op_cancel(VALUE self, VALUE vid) {
-    winloop_backend *b = get_backend_ops(self);
-    winloop_op *op = op_lookup(b, NUM2ULL(vid));
-    DWORD gle;
-    if (op->state == OP_PREPARED)
-        rb_raise(eError, "winloop: op %llu is prepared; only a submitted op can be "
-                 "cancelled (a prepared op is retired with op_abandon)",
-                 (unsigned long long)op->id);
-    if (CancelIoEx(op->handle, &op->ov)) return Qtrue;
-    gle = GetLastError(); /* captured immediately, before any Ruby call */
-    if (gle != ERROR_NOT_FOUND)
-        rb_warn("winloop: CancelIoEx for op %llu failed (error %lu) — treated as "
-                "no-cancel, never an exception", (unsigned long long)op->id, gle);
-    return Qfalse;
-}
-
-/* [bytes, error, data] for a COMPLETED op; frees the record. The String is built
- * BEFORE the free so an OOM raise leaves the op intact and retryable. `data` is
- * clamped to min(bytes, capacity): a stray packet's bogus byte count cannot make
- * winloop read past its own buffer. */
-static VALUE backend_op_result(VALUE self, VALUE vid) {
-    winloop_backend *b = get_backend_ops(self);
-    winloop_op *op = op_lookup(b, NUM2ULL(vid));
-    VALUE data = Qnil, result;
-    if (op->state != OP_COMPLETED)
-        rb_raise(eError, "winloop: op %llu is %s; op_result is only legal once its "
-                 "completion has been reaped by #wait",
-                 (unsigned long long)op->id, op_state_name(op->state));
-    if (op->cap) {
-        size_t n = (size_t)op->bytes < op->cap ? (size_t)op->bytes : op->cap;
-        data = rb_str_new((const char *)op + OP_BUF_OFFSET, (long)n); /* ASCII-8BIT */
-    }
-    result = rb_ary_new_from_args(3, ULONG2NUM(op->bytes), ULONG2NUM(op->error), data);
-    op_retire(b, op);
-    return result;
-}
-
-/* Retire a COMPLETED op without materializing its data (orphaned completions). */
-static VALUE backend_op_free(VALUE self, VALUE vid) {
-    winloop_backend *b = get_backend_ops(self);
-    winloop_op *op = op_lookup(b, NUM2ULL(vid));
-    if (op->state != OP_COMPLETED)
-        rb_raise(eError, "winloop: op %llu is %s; op_free is only legal once its "
-                 "completion has been reaped by #wait",
-                 (unsigned long long)op->id, op_state_name(op->state));
-    op_retire(b, op);
-    return Qtrue;
-}
-
-static VALUE backend_op_state(VALUE self, VALUE vid) {
-    winloop_backend *b = get_backend_ops(self);
-    winloop_op *op = op_lookup(b, NUM2ULL(vid));
-    switch (op->state) {
-      case OP_PREPARED:  return ID2SYM(rb_intern("prepared"));
-      case OP_SUBMITTED: return ID2SYM(rb_intern("submitted"));
-      default:           return ID2SYM(rb_intern("completed"));
-    }
-}
-
-/* The raw IOCP HANDLE value — read-only, for tests and diagnostics. Hard rules:
- * never wait on it, never close it, never associate handles behind winloop's
- * back, never post after shutdown, at most ONE post per op. */
-static VALUE backend_port_handle(VALUE self) {
-    winloop_backend *b = get_backend_ops(self);
-    return ULL2NUM((uintptr_t)b->iocp);
-}
-
-/* Reap completions in one GetQueuedCompletionStatusEx. Returns an Array of
-   [id, ready_events]; wakeup packets are skipped. Empty array on timeout. */
-/* The blocking GQCSEx call, run WITHOUT the GVL so other threads (and the very
-   producer that will call #unblock) can run while the loop sleeps on the port. */
-typedef struct {
-    HANDLE iocp;
-    OVERLAPPED_ENTRY *ents;
-    ULONG cap, n;
-    DWORD ms, err;
-    BOOL ok;
-} gqcs_args;
-
-static void *gqcs_call(void *p) {
-    gqcs_args *a = (gqcs_args *)p;
-    a->ok  = GetQueuedCompletionStatusEx(a->iocp, a->ents, a->cap, &a->n, a->ms, FALSE);
-    a->err = a->ok ? 0 : GetLastError();
-    return NULL;
-}
-
-/* Ruby's interrupt path (signals, Thread#kill): wake the GQCSEx so the loop
-   thread can return to Ruby and check interrupts. */
-static void gqcs_ubf(void *p) {
-    PostQueuedCompletionStatus((HANDLE)p, 0, WAKE_KEY, NULL);
-}
-
-static VALUE backend_wait(VALUE self, VALUE vtimeout_ms) {
-    winloop_backend *b = get_backend(self);
-    DWORD ms = NIL_P(vtimeout_ms) ? INFINITE : (DWORD)NUM2ULONG(vtimeout_ms);
-    OVERLAPPED_ENTRY ents[REAP_CAP];
-
-    gqcs_args a = { b->iocp, ents, REAP_CAP, 0, ms, 0, FALSE };
-    rb_thread_call_without_gvl(gqcs_call, &a, gqcs_ubf, b->iocp);
-    BOOL ok = a.ok;
-    DWORD err = a.err;
-    ULONG n = a.n;
-
-    VALUE result = rb_ary_new();
-    if (!ok) {
-        if (err == WAIT_TIMEOUT) return result;
-        rb_raise(eError, "winloop: GetQueuedCompletionStatusEx failed (%lu)", err);
-    }
-    for (ULONG i = 0; i < n; i++) {
-        if (ents[i].lpCompletionKey == WAKE_KEY || ents[i].lpOverlapped == NULL) continue;
-        if (ents[i].lpCompletionKey == EXT_KEY) {
-            /* Generic-op path (winloop 0.2). Defensive dispatch: verify membership
-             * in ops_by_addr AND op state before acting — an unknown lpOverlapped
-             * is never cast, an already-COMPLETED op (double post) is never
-             * re-completed and never yields a second tuple. The only accepted
-             * anomaly is a packet for a still-PREPARED op (a standalone embedder
-             * called #wait between the native submit and op_submitted): the packet
-             * is real and the memory is ours, so accept it with a warning. */
-            st_data_t val;
-            winloop_op *op;
-            if (!st_lookup(b->ops_by_addr, (st_data_t)(uintptr_t)ents[i].lpOverlapped, &val)) {
-                rb_warn("winloop: dropped a completion packet for an unknown OVERLAPPED "
-                        "0x%llx (stray or duplicate post)",
-                        (unsigned long long)(uintptr_t)ents[i].lpOverlapped);
-                continue;
-            }
-            op = (winloop_op *)val;
-            if (op->state == OP_COMPLETED) {
-                rb_warn("winloop: dropped a duplicate completion packet for op %llu "
-                        "(already completed; bytes/error preserved)",
-                        (unsigned long long)op->id);
-                continue;
-            }
-            if (op->state == OP_PREPARED)
-                rb_warn("winloop: completion packet reaped for op %llu before "
-                        "op_submitted (protocol violation; accepting the packet)",
-                        (unsigned long long)op->id);
-            op->state = OP_COMPLETED;
-            op->bytes = ents[i].dwNumberOfBytesTransferred;
-            /* Status lives in the OVERLAPPED's Internal (an NTSTATUS), readable
-             * only after the packet left the port; map it to a familiar Win32
-             * code (0 ok, 995 cancelled, 1022 rescan, 38 EOF, ...). */
-            op->error = pRtlNtStatusToDosError((NTSTATUS)op->ov.Internal);
-            rb_ary_push(result, rb_ary_new_from_args(4, ULL2NUM(op->id),
-                        ULONG2NUM(op->bytes), ULONG2NUM(op->error), ULL2NUM(op->tag)));
-            continue;
-        }
-        /* AFD path — byte-for-byte the pre-0.2 code (only the AFD handle carries
-         * AFD_KEY on this port). */
-        winloop_req *req = (winloop_req *)ents[i].lpOverlapped;
-        st_data_t key = (st_data_t)req->id;
-        st_delete(b->reqs, &key, NULL);
-        int events = afd_to_ruby(req->out.Handles[0].Events);
-        VALUE pair = rb_ary_new_from_args(2, ULL2NUM(req->id), INT2NUM(events));
-        rb_ary_push(result, pair);
-        xfree(req);
-    }
-    return result;
-}
-
-static VALUE backend_wakeup(VALUE self) {
-    winloop_backend *b = get_backend(self);
-    PostQueuedCompletionStatus(b->iocp, 0, WAKE_KEY, NULL);
-    return Qnil;
-}
-
-static VALUE backend_shutdown(VALUE self) {
-    winloop_backend *b;
-    TypedData_Get_Struct(self, winloop_backend, &backend_type, b);
-    if (b) backend_drain_and_close(b);
-    return Qnil;
-}
-
-void Init_winloop(void) {
-    WSADATA wsa;
-    WSAStartup(MAKEWORD(2, 2), &wsa);
-
-    mWinloop = rb_define_module("Winloop");
-    cBackend = rb_define_class_under(mWinloop, "Backend", rb_cObject);
-    eError   = rb_define_class_under(mWinloop, "Error", rb_eStandardError);
-
-    /* Export the Ruby IO event bits the scheduler/backend agree on. */
-    rb_define_const(mWinloop, "READABLE", INT2NUM(RB_READABLE));
-    rb_define_const(mWinloop, "WRITABLE", INT2NUM(RB_WRITABLE));
-    rb_define_const(mWinloop, "PRIORITY", INT2NUM(RB_PRIORITY));
-
-    /* The completion key winloop assigns to ALL generic ops on the port
-     * (internal dispatch; exposed for tests and a possible future injection
-     * protocol — PQCS injection is NOT a v1 protocol). */
-    rb_define_const(mWinloop, "EXTERNAL_KEY", ULL2NUM(0x45585431ull));
-
-    rb_define_alloc_func(cBackend, backend_alloc);
-    rb_define_method(cBackend, "initialize", RUBY_METHOD_FUNC(backend_initialize), 0);
-    rb_define_method(cBackend, "poll",       RUBY_METHOD_FUNC(backend_poll), 2);
-    rb_define_method(cBackend, "cancel",     RUBY_METHOD_FUNC(backend_cancel), 1);
-    rb_define_method(cBackend, "wait",       RUBY_METHOD_FUNC(backend_wait), 1);
-    rb_define_method(cBackend, "wakeup",     RUBY_METHOD_FUNC(backend_wakeup), 0);
-    rb_define_method(cBackend, "shutdown",   RUBY_METHOD_FUNC(backend_shutdown), 0);
-
-    /* Generic OVERLAPPED ops (winloop 0.2). `_op_prepare` is the private bridge
-     * behind the validated Winloop::Backend#op_prepare in lib/winloop/ops.rb. */
-    rb_define_method(cBackend, "associate",    RUBY_METHOD_FUNC(backend_associate), 1);
-    rb_define_method(cBackend, "_op_prepare",  RUBY_METHOD_FUNC(backend__op_prepare), 3);
-    rb_define_method(cBackend, "op_submitted", RUBY_METHOD_FUNC(backend_op_submitted), 1);
-    rb_define_method(cBackend, "op_abandon",   RUBY_METHOD_FUNC(backend_op_abandon), 1);
-    rb_define_method(cBackend, "op_cancel",    RUBY_METHOD_FUNC(backend_op_cancel), 1);
-    rb_define_method(cBackend, "op_result",    RUBY_METHOD_FUNC(backend_op_result), 1);
-    rb_define_method(cBackend, "op_free",      RUBY_METHOD_FUNC(backend_op_free), 1);
-    rb_define_method(cBackend, "op_state",     RUBY_METHOD_FUNC(backend_op_state), 1);
-    rb_define_method(cBackend, "port_handle",  RUBY_METHOD_FUNC(backend_port_handle), 0);
-}