winloop 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 52ea4b37e9fbf3f00710317ae3ce66560b014a39103fcd731c825c77ec8367b5
+  data.tar.gz: c137e9507075259aaec8a604b5937bb305c8ed6134f33b54cecc8c19b756c21f
+SHA512:
+  metadata.gz: 5406ad357675a336f7fece41a9a4f986449a71d29324b40eb1b852851517d25310417c0e88026bd353de16dd9cf4c9bcc735c7c799a298da8e08937176ad86f2
+  data.tar.gz: fc833ec7d8d95317b010f9c25b5acae10db5366ce30ffb881c922ca05fb38fa480b928b14830758f1e4b4b02432b40d45dfb0cb7b06a31aa32db4693fcbd6059

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+* A `Fiber::Scheduler` for MRI on Windows backed by I/O Completion Ports.
+* C backend (`Winloop::Backend`): one IOCP plus a `\Device\Afd` handle, with
+  one-shot readiness polls (`IOCTL_AFD_POLL`) submitted as overlapped operations
+  on the port, reaped in batches via `GetQueuedCompletionStatusEx`. The wait runs
+  without the GVL so background threads can wake the loop with
+  `PostQueuedCompletionStatus`.
+* Scheduler hooks: `io_wait`, `io_read`, `io_write`, `kernel_sleep`,
+  `timeout_after`, `block`/`unblock`, `fiber`, `address_resolve`, `process_wait`,
+  and `close` (which drives the event loop).
+* Monotonic timer min-heap for `sleep` and `Timeout.timeout`.
+* `Winloop.run { ... }` convenience entry point.
+* Verified with TCP echo over many concurrent connections, large multi-chunk
+  transfers, EOF handling, `Timeout` (both firing and not), cross-thread `Queue`,
+  inter-fiber `Mutex` contention, `Thread#join`, DNS resolution, and `IO.popen`.
+
+  Hardened over three rounds of adversarial review (the GVL is released around the
+  completion wait so background threads can wake the loop):
+  * AFD readiness polls are **coalesced per socket** — multiple fibers waiting the
+    same socket for the same event all wake (the AFD driver only completes one poll
+    per readiness edge, so independent polls would lose wakeups).
+  * Cross-thread wakeups are unified through a single per-fiber guard, so a timeout
+    timer racing an `unblock` (e.g. `ConditionVariable#wait(mutex, timeout)` racing a
+    signal, or `Thread#join(timeout)` near its deadline) can never double-resume a
+    fiber and cut its next wait short.
+  * Settled timers are dropped from the heap so an early-resolved wait can't pin the
+    loop asleep until its original (possibly long) timeout.
+  * An unhandled exception in a scheduled fiber is reported, not fatal to the loop.
+  * The non-socket read fallback runs on a worker thread that is killed if its fiber
+    unwinds, so it can't leak or steal data; pipe EOF is silent.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,131 @@
+# winloop
+
+A native **Windows** Fiber Scheduler for MRI Ruby, built on **I/O Completion Ports**.
+
+`winloop` makes ordinary blocking code — socket reads and writes, `sleep`,
+`Timeout.timeout`, `Mutex`, `Queue`, `Thread#join`, DNS lookups — run
+cooperatively on a single thread. Wrap your code in `Winloop.run { ... }`,
+spawn fibers with `Fiber.schedule`, and thousands of connections share one
+thread without you touching a single nonblocking API.
+
+```ruby
+require "winloop"
+require "socket"
+
+Winloop.run do
+  server = TCPServer.new("127.0.0.1", 9292)
+  loop do
+    client = server.accept                 # readiness via AFD poll on the IOCP
+    Fiber.schedule do                       # one lightweight fiber per connection
+      while (line = client.gets)            # recv driven by the completion port
+        client.write(line)                  # send, never blocking the loop
+      end
+      client.close
+    end
+  end
+end
+```
+
+## Why this exists
+
+Ruby's `Fiber::Scheduler` (the engine behind `socketry/async` and friends) is the
+modern way to write concurrent I/O. But on Windows the selectors that back it —
+`socketry/io-event` ships `select`, `epoll`, `kqueue`, and `io_uring` — have **no
+IOCP backend**. The result has long been the weakest async story of any major
+platform: `select()`-bound, capped at 64 handles, and slow.
+
+`winloop` fills that hole the same way libuv, Rust's mio, and wepoll do it:
+
+* The event loop is a real **I/O Completion Port**. One
+  `GetQueuedCompletionStatusEx` call per turn reaps every ready event at once.
+* **Readiness** (accept, connect, `IO#wait_readable`) — which IOCP doesn't natively
+  provide — is obtained by submitting `IOCTL_AFD_POLL` against `\Device\Afd` as an
+  overlapped operation on the port. This is the undocumented mechanism libuv/mio
+  rely on, and it is the only way to get readiness semantics onto a completion port.
+* **Reads and writes** are driven by `recv`/`send` once the port reports readiness.
+* **Timers** (`sleep`, `Timeout.timeout`) use a monotonic min-heap that sets the
+  port's wait timeout — no kernel timer objects, no extra threads.
+* **`Mutex`/`Queue`/`Thread#join`** park the fiber on an in-process waiter list; a
+  wakeup from another OS thread breaks the loop's wait via
+  `PostQueuedCompletionStatus`.
+
+## Requirements
+
+* A **native Windows MSVC build of Ruby** (`x64-mswin64`). winloop compiles a C
+  extension with `cl.exe` and links `ws2_32`. It will refuse to install on any
+  non-`mswin` platform.
+* Ruby >= 3.1 (for a stable `Fiber::Scheduler` and `IO::Buffer`).
+* `\Device\Afd` readiness polling is a Windows NT facility; winloop is **not**
+  expected to work under Wine.
+
+## Installation
+
+```sh
+gem install winloop
+```
+
+Or build from a checkout (it dogfoods the [`vcvars`](https://rubygems.org/gems/vcvars)
+gem so it can find the MSVC toolchain without a Developer Command Prompt):
+
+```sh
+rake compile
+rake test
+```
+
+## What runs cooperatively
+
+Inside `Winloop.run { ... }` (and any `Fiber.schedule` started within it):
+
+| Operation                                  | Hook            | Mechanism                              |
+| ------------------------------------------ | --------------- | -------------------------------------- |
+| `TCPServer#accept`, `IO#wait_readable`     | `io_wait`       | `IOCTL_AFD_POLL` overlapped on the IOCP |
+| `IO#read` / `gets` / `recv` on a socket    | `io_read`       | `recv_nonblock` + `io_wait`             |
+| `IO#write` / `puts` on a socket            | `io_write`      | `write_nonblock` + `io_wait`            |
+| `sleep`                                     | `kernel_sleep`  | monotonic timer heap                   |
+| `Timeout.timeout`                           | `timeout_after` | timer heap + `Fiber#raise`             |
+| `Mutex`, `ConditionVariable`, `Queue`, `Thread#join` | `block`/`unblock` | waiter lists + `PostQueuedCompletionStatus` |
+| `Addrinfo.getaddrinfo`, DNS in `TCPSocket.new` | `address_resolve` | resolved on a worker thread        |
+| `Process.wait`                              | `process_wait`  | reaped on a worker thread              |
+
+## API
+
+```ruby
+Winloop.run { ... }   # install a scheduler, run the block in a fiber, drive the
+                      # loop until every scheduled fiber finishes; returns the
+                      # block's value (and re-raises anything it raised).
+
+Winloop.supported?    # true when the native IOCP/AFD backend loaded.
+```
+
+For full control you can drive it yourself, exactly like any other
+`Fiber::Scheduler`:
+
+```ruby
+scheduler = Winloop::Scheduler.new
+Fiber.set_scheduler(scheduler)
+Fiber.schedule { ... }
+scheduler.close       # runs the event loop to completion
+```
+
+## Scope and limitations (v0.1)
+
+* **Sockets are the focus.** TCP/UDP sockets get the full IOCP/AFD path. Pipes and
+  regular files fall back to a blocking read inside `io_read` (async file I/O on
+  Windows is a separate mechanism, planned for later).
+* **Single thread-of-use.** One thread runs the loop and resumes fibers; other OS
+  threads may safely wake it (e.g. a background `Queue` producer), but the loop
+  itself is not a multi-threaded worker pool.
+* `IOCTL_AFD_POLL` is undocumented; winloop resolves its `ntdll` entry points at
+  runtime and degrades by raising a clear error if `\Device\Afd` is unavailable.
+
+## How it compares
+
+`winloop` is a drop-in `Fiber::Scheduler`, so it works with anything that targets
+the scheduler interface. It is *not* a reimplementation of `async` — it's the
+missing Windows engine such libraries can run on. The reference scheduler shipped
+with Ruby is intended for testing and is `IO.select`-bound; winloop replaces that
+selector with a true completion port.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/ext/winloop/extconf.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+#
+# extconf.rb for the winloop C backend (IOCP + \Device\Afd readiness).
+
+require "mkmf"
+
+unless RbConfig::CONFIG["target_os"] =~ /mswin/
+  abort <<~MSG
+    winloop requires a native Windows MSVC (mswin) Ruby — its event loop is built
+    on Win32 I/O Completion Ports and \\Device\\Afd readiness polling (cl.exe).
+    Your Ruby is "#{RbConfig::CONFIG['arch']}".
+  MSG
+end
+
+# Winsock. (ntdll's Nt*/Rtl* entry points are resolved at runtime via
+# GetProcAddress, so no ntdll import lib is required.) Pure C — no -EHsc.
+$libs = [$libs, "ws2_32.lib"].join(" ")
+
+create_makefile("winloop/winloop")

data/ext/winloop/winloop.c

@@ -0,0 +1,358 @@
+/*
+ * 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 REAP_CAP 64
+
+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);
+
+static PFN_NtCreateFile          pNtCreateFile;
+static PFN_NtDeviceIoControlFile pNtDeviceIoControlFile;
+static PFN_RtlInitUnicodeString  pRtlInitUnicodeString;
+
+#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;
+
+typedef struct {
+    HANDLE     iocp;
+    HANDLE     afd;
+    uint64_t   next_id;
+    st_table  *reqs;   /* id -> winloop_req* */
+    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");
+    return pNtCreateFile && pNtDeviceIoControlFile && pRtlInitUnicodeString;
+}
+
+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;
+}
+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);
+    }
+    /* 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) {
+            /* drop them; the requests are freed below from the table */
+        }
+    }
+    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; }
+}
+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) { (void)p; return sizeof(winloop_backend); }
+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;
+}
+
+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();
+    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;
+}
+
+/* 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;
+        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));
+
+    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);
+}

data/lib/winloop/scheduler.rb

@@ -0,0 +1,496 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Winloop
+  # A Fiber::Scheduler for MRI on Windows, backed by an I/O Completion Port.
+  #
+  # Strategy (matches libuv/mio/wepoll on Windows):
+  #   * io_wait          -> IOCTL_AFD_POLL submitted as an overlapped op on the IOCP
+  #                         (the only way to get *readiness* onto a completion port).
+  #                         Polls are COALESCED per socket: at most one AFD poll is
+  #                         outstanding per socket, covering the union of every
+  #                         waiter's interest, and its completion fans out to all of
+  #                         them. (The AFD driver completes only ONE pending poll per
+  #                         readiness edge, so independent polls on the same socket
+  #                         would lose wakeups.)
+  #   * io_read/io_write -> recv_nonblock/write_nonblock driven by io_wait
+  #   * kernel_sleep /
+  #     timeout_after    -> a monotonic timer min-heap (the loop's GQCSEx timeout)
+  #   * block / unblock  -> in-process waiter lists; cross-thread unblock wakes the
+  #                         loop with PostQueuedCompletionStatus
+  #   * close            -> drives the run loop until every fiber has finished
+  #
+  # Single thread-of-use: only the owning thread runs the loop and resumes fibers.
+  # #unblock may be called from another thread and only mutates the (locked) ready
+  # queue + posts a wakeup; it never resumes a fiber itself.
+  class Scheduler
+    # One blocking wait. `settled` is the one-shot guard: whoever wakes the fiber
+    # first (I/O completion, timeout, or unblock) sets it; everyone else skips.
+    Waiter = Struct.new(:fiber, :settled)
+
+    # One fiber waiting on a socket for `events` (an io_wait waiter).
+    IoWaiter = Struct.new(:fiber, :events, :settled)
+
+    # The single outstanding AFD poll for one socket, shared by its io waiters.
+    PollEntry = Struct.new(:key, :io, :id, :armed, :waiters)
+
+    # A timer heap node. `value` is what the fiber is resumed with when it fires;
+    # `raise_exc` (for Timeout.timeout) makes it raise into the fiber instead.
+    Timer = Struct.new(:deadline, :waiter, :value, :raise_exc)
+
+    def initialize
+      @backend = Backend.new
+      @ready   = []     # [[fiber, resume_value], ...]   (shared: unblock pushes here)
+      @timers  = MinHeap.new # of Timer, keyed on :deadline
+      @polls   = {}     # socket key (fileno) => PollEntry
+      @ops     = {}     # backend poll id => PollEntry
+      @parked  = {}     # fiber => Waiter   (its CURRENT block/kernel_sleep park)
+      @lock    = Thread::Mutex.new # guards @ready + @parked (the cross-thread path)
+      @loop    = Fiber.current     # the thread's root fiber == the loop
+      @closed  = false
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # ---- I/O readiness (accept / connect / IO#wait) -----------------------
+
+    # Wait until `io` is ready for `events`; returns the ready-events bitmask
+    # (0 on timeout). events is an OR of Winloop::READABLE/WRITABLE/PRIORITY.
+    def io_wait(io, events, timeout)
+      key    = io.fileno
+      waiter = IoWaiter.new(Fiber.current, events, false)
+      entry  = (@polls[key] ||= PollEntry.new(key, io, nil, 0, []))
+      entry.waiters << waiter
+      arm_poll(entry)
+      @timers.push(Timer.new(monotonic + timeout, waiter, 0, nil)) if timeout
+      Fiber.yield # resumed with the ready-events mask (or 0 on timeout)
+    ensure
+      # On the normal completion path the loop already removed us from the entry
+      # and re-armed/dropped it. If we are unwinding by any other path (timeout,
+      # or Timeout.timeout raised into us), detach and re-arm/cancel for the rest.
+      waiter.settled = true
+      if entry.waiters.delete(waiter)
+        if entry.waiters.empty?
+          cancel_entry(entry)
+        else
+          arm_poll(entry) # interest shrank; existing poll still covers it (no-op)
+        end
+      end
+    end
+
+    # ---- stream read/write (recv_nonblock + io_wait) ----------------------
+    #
+    # `length` is the MINIMUM bytes to transfer; 0 means "the whole region
+    # [offset, buffer.size)". MUST use recv_nonblock — read_nonblock / sysread /
+    # readpartial re-enter this hook on mswin and recurse forever.
+
+    def io_read(io, buffer, length, offset = 0)
+      return blocking_read(io, buffer, length, offset) unless io.respond_to?(:recv_nonblock)
+      total   = 0
+      minimum = length.zero? ? 1 : length
+      while total < minimum
+        maximum = buffer.size - offset - total
+        break if maximum <= 0
+        result = io.recv_nonblock(maximum, exception: false)
+        case result
+        when :wait_readable then io_wait(io, READABLE, nil)
+        when nil then break # EOF
+        else
+          buffer.set_string(result, offset + total)
+          total += result.bytesize
+        end
+      end
+      total
+    end
+
+    def io_write(io, buffer, length, offset = 0)
+      total   = 0
+      maximum = buffer.size - offset
+      return 0 if maximum <= 0
+      minimum = length.zero? ? maximum : length
+      minimum = maximum if minimum > maximum # never spin writing empty chunks
+      while total < minimum
+        chunk = buffer.get_string(offset + total, maximum - total)
+        break if chunk.empty?
+        result = io.write_nonblock(chunk, exception: false)
+        if result == :wait_writable
+          io_wait(io, WRITABLE, nil)
+        else
+          total += result
+        end
+      end
+      total
+    end
+
+    # ---- timers -----------------------------------------------------------
+
+    def kernel_sleep(duration = nil)
+      fiber  = Fiber.current
+      waiter = Waiter.new(fiber, false)
+      # Park under @parked so a cross-thread #unblock (e.g. ConditionVariable#wait
+      # with a timeout parks HERE, and a racing signal must wake us through the
+      # SAME one-shot guard as the timer — never a second, competing wakeup).
+      @lock.synchronize { @parked[fiber] = waiter }
+      @timers.push(Timer.new(monotonic + duration, waiter, nil, nil)) if duration
+      Fiber.yield
+      duration
+    ensure
+      @lock.synchronize do
+        waiter.settled = true # disarm a not-yet-fired timer on abnormal exit
+        @parked.delete(fiber)
+      end
+    end
+
+    def timeout_after(duration, exception_class, *exception_arguments)
+      waiter = Waiter.new(Fiber.current, false)
+      @timers.push(Timer.new(monotonic + duration, waiter, nil,
+                             [exception_class, exception_arguments]))
+      begin
+        yield duration
+      ensure
+        # disarm if the block finished before the deadline
+        @lock.synchronize { waiter.settled = true }
+      end
+    end
+
+    # ---- block / unblock (Mutex, ConditionVariable, Queue, Thread#join) ----
+
+    def block(blocker, timeout = nil)
+      fiber  = Fiber.current
+      waiter = Waiter.new(fiber, false)
+      @lock.synchronize { @parked[fiber] = waiter }
+      @timers.push(Timer.new(monotonic + timeout, waiter, false, nil)) if timeout
+      Fiber.yield # true (unblocked) or false (timed out)
+    ensure
+      @lock.synchronize do
+        waiter.settled = true
+        @parked.delete(fiber)
+      end
+    end
+
+    # Called from ANY thread: only mutate shared state under the lock and wake
+    # the loop — never resume the fiber here.
+    #
+    # We wake by FIBER identity through its single parked Waiter, ignoring
+    # `blocker`. That is deliberate and important:
+    #   * Thread#join calls block(thread) but MRI calls unblock(<a DIFFERENT
+    #     object>, fiber); keying on the fiber wakes it correctly anyway.
+    #   * A fiber can have more than one live wakeup source (a timeout timer AND
+    #     this unblock — e.g. ConditionVariable#wait(mutex, timeout) racing a
+    #     signal). Routing through the one Waiter's `settled` guard means exactly
+    #     one of them resumes the fiber; the loser is dropped. A raw, unguarded
+    #     "@ready << fiber" would double-resume and cut the fiber's NEXT wait short.
+    def unblock(_blocker, fiber)
+      @lock.synchronize do
+        waiter = @parked[fiber]
+        if waiter
+          wake_locked(waiter, true)
+        elsif @ready.none? { |f, _| f.equal?(fiber) }
+          # Not parked in any wait we track (spurious/late unblock) — last resort,
+          # de-duplicated so it can never double-enqueue.
+          @ready << [fiber, true]
+        end
+      end
+      @backend.wakeup
+    end
+
+    # ---- fiber creation ----------------------------------------------------
+
+    def fiber(&block)
+      fiber = Fiber.new(blocking: false, &block)
+      fiber.resume
+      fiber
+    end
+
+    # ---- optional hooks (offloaded to a thread; the originals re-enter) -----
+
+    # Run a blocking operation on a fresh, scheduler-FREE thread and park the
+    # calling fiber on it cooperatively (Thread#value -> our block hook). The
+    # worker is killed if this fiber unwinds first (Timeout.timeout / Fiber kill)
+    # so it can never outlive us, leak, or race a later operation. We do NOT
+    # join after kill — that would re-enter the scheduler mid-unwind; Thread#kill
+    # interrupts the blocking syscall and the worker terminates on its own.
+    def await_on_thread(&block)
+      worker = Thread.new(&block)
+      worker.report_on_exception = false # expected errors are surfaced via #value
+      begin
+        worker.value
+      ensure
+        if worker.alive?
+          # Unwound first (Timeout/kill): interrupt the worker out of its blocking
+          # syscall and WAIT for it to die before returning, so it can't read (and
+          # discard) bytes that a later operation on the same IO expects. kill
+          # interrupts readpartial immediately, so this join does not block.
+          worker.kill
+          worker.join
+        end
+      end
+    end
+
+    def address_resolve(hostname)
+      await_on_thread do
+        Addrinfo.getaddrinfo(hostname, nil, nil, :STREAM).map(&:ip_address).uniq
+      end
+    rescue SocketError
+      []
+    end
+
+    def process_wait(pid, flags)
+      await_on_thread { Process::Status.wait(pid, flags) }
+    end
+
+    # ---- lifecycle ---------------------------------------------------------
+
+    # MRI calls this automatically at thread/program exit. It IS the event loop.
+    def close
+      return if @closed
+      @closed = true
+      run
+    ensure
+      @backend.shutdown
+      # NEVER call Fiber.set_scheduler(nil) here — it raises SystemStackError
+      # during MRI's implicit close at thread exit.
+    end
+
+    def closed? = @closed
+
+    # ---- the run loop ------------------------------------------------------
+
+    def run
+      run_once until done?
+    end
+
+    private
+
+    def done?
+      # Locked so the "are we idle?" decision is atomic against a cross-thread
+      # #unblock that is moving a waiter into @ready right now.
+      @lock.synchronize do
+        drop_settled_timers
+        @ready.empty? && @timers.empty? && @ops.empty? && @parked.empty?
+      end
+    end
+
+    def run_once
+      # (a) resume everything currently ready (outside the lock — resume runs
+      #     arbitrary Ruby which may re-enter the scheduler). An unhandled error
+      #     in a scheduled child fiber is reported, not fatal to the loop
+      #     (Thread-like); the main block's own errors are handled by Winloop.run.
+      ready = @lock.synchronize { r = @ready; @ready = []; r }
+      ready.each do |fiber, value|
+        next unless fiber.alive?
+        begin
+          fiber.resume(value)
+        rescue StandardError => e
+          report_fiber_error(e)
+        end
+      end
+
+      # (b) fire expired timers (skipping any already settled by another path)
+      drop_settled_timers
+      now = monotonic
+      while (t = @timers.peek) && t.deadline <= now
+        @timers.pop
+        next if t.waiter.settled
+        if t.raise_exc
+          t.waiter.settled = true
+          klass, args = t.raise_exc
+          f = t.waiter.fiber
+          begin
+            f.raise(klass, *args) if f.alive?
+          rescue StandardError => e
+            report_fiber_error(e)
+          end
+        else
+          @lock.synchronize { wake_locked(t.waiter, t.value) }
+        end
+        drop_settled_timers
+      end
+
+      # (c) compute the single-wait timeout. The idle decision is taken under
+      #     the lock so a concurrent #unblock can't slip a ready fiber past us.
+      timeout_ms = nil
+      idle = false
+      @lock.synchronize do
+        drop_settled_timers
+        if !@ready.empty?
+          timeout_ms = 0
+        elsif (t = @timers.peek)
+          ms = ((t.deadline - monotonic) * 1000).ceil
+          timeout_ms = ms < 0 ? 0 : ms
+        elsif @ops.empty? && @parked.empty?
+          idle = true # nothing to wait for
+        else
+          timeout_ms = nil # INFINITE — pending I/O or parked fibers wake us
+        end
+      end
+      return if idle
+
+      # (d) one GetQueuedCompletionStatusEx; fan each completion out to the
+      #     io waiters whose interest the ready mask satisfies.
+      @backend.wait(timeout_ms).each do |id, ready_events|
+        entry = @ops.delete(id)
+        next unless entry # stale: a superseded/cancelled poll
+        entry.id = nil
+        entry.armed = 0
+        to_wake = []
+        entry.waiters.reject! do |w|
+          if w.settled
+            true
+          elsif (got = w.events & ready_events) != 0
+            w.settled = true
+            to_wake << [w.fiber, got]
+            true
+          else
+            false # this waiter's direction didn't fire; keep it
+          end
+        end
+        @lock.synchronize { @ready.concat(to_wake) } unless to_wake.empty?
+        if entry.waiters.empty?
+          @polls.delete(entry.key)
+        else
+          arm_poll(entry) # re-arm for the still-waiting fibers
+        end
+      end
+    end
+
+    # Ensure at most one AFD poll is outstanding for `entry`'s socket, covering
+    # the union of all its waiters' interests. Re-arms only when the union grows.
+    def arm_poll(entry)
+      union = entry.waiters.inject(0) { |m, w| m | w.events }
+      return if union.zero?
+      return if entry.id && (union & ~entry.armed).zero? # current poll covers it
+
+      if entry.id
+        @ops.delete(entry.id)
+        @backend.cancel(entry.id) # its cancelled completion is reaped + ignored later
+        entry.id = nil
+      end
+      begin
+        entry.id = @backend.poll(entry.io, union)
+        entry.armed = union
+        @ops[entry.id] = entry
+      rescue Winloop::Error
+        # Socket vanished/closed mid-wait: wake every waiter so the follow-up
+        # recv/send surfaces the real error instead of hanging here.
+        to_wake = []
+        entry.waiters.each do |w|
+          next if w.settled
+          w.settled = true
+          to_wake << [w.fiber, w.events]
+        end
+        entry.waiters.clear
+        @lock.synchronize { @ready.concat(to_wake) } unless to_wake.empty?
+        @polls.delete(entry.key)
+      end
+    end
+
+    def cancel_entry(entry)
+      if entry.id
+        @ops.delete(entry.id)
+        @backend.cancel(entry.id)
+        entry.id = nil
+      end
+      @polls.delete(entry.key)
+    end
+
+    # Discard settled timers from the heap top so done? and the wait-timeout
+    # computation never block on a timer whose fiber already woke another way.
+    def drop_settled_timers
+      @timers.pop while (t = @timers.peek) && t.waiter.settled
+    end
+
+    # Enqueue a fiber to resume, honouring the one-shot guard. Caller holds @lock.
+    def wake_locked(waiter, value)
+      return if waiter.settled
+      waiter.settled = true
+      @ready << [waiter.fiber, value]
+    end
+
+    def report_fiber_error(error)
+      return unless Thread.report_on_exception
+      warn "winloop: unhandled exception in scheduled fiber: #{error.class}: #{error.message}"
+      warn(error.backtrace.first(10).map { |l| "\tfrom #{l}" }.join("\n")) if error.backtrace
+    rescue StandardError
+      # never let error reporting itself break the loop
+    end
+
+    # Degraded path for non-socket IO (pipes, the console — no AFD readiness).
+    #
+    # The read runs on a scheduler-free worker thread (see await_on_thread) so
+    # IO#readpartial there is a genuine blocking syscall instead of re-dispatching
+    # back into this io_read hook (which would recurse to a SystemStackError),
+    # while the calling fiber parks cooperatively and the loop keeps serving
+    # others. `want` is clamped to the buffer's free region so set_string can't
+    # overflow. Note: non-socket IO is best-effort — if THIS read is unwound by a
+    # Timeout, bytes the worker had already pulled off the stream are lost (you
+    # can't un-read). Sockets are the first-class path.
+    def blocking_read(io, buffer, length, offset)
+      maximum = buffer.size - offset
+      return 0 if maximum <= 0
+      want = length.zero? ? maximum : [length, maximum].min
+      data =
+        begin
+          await_on_thread { io.readpartial(want) }
+        rescue EOFError, IOError
+          nil
+        end
+      return 0 if data.nil? || data.empty?
+      buffer.set_string(data, offset)
+      data.bytesize
+    end
+  end
+
+  # A tiny binary min-heap keyed on the node's #deadline. Enough for timers.
+  class MinHeap
+    def initialize
+      @a = []
+    end
+
+    def empty? = @a.empty?
+    def size = @a.size
+    def peek = @a[0]
+
+    def push(node)
+      @a << node
+      i = @a.size - 1
+      while i > 0
+        parent = (i - 1) / 2
+        break if @a[parent].deadline <= @a[i].deadline
+        @a[parent], @a[i] = @a[i], @a[parent]
+        i = parent
+      end
+      node
+    end
+
+    def pop
+      return nil if @a.empty?
+      top = @a[0]
+      last = @a.pop
+      unless @a.empty?
+        @a[0] = last
+        sift_down(0)
+      end
+      top
+    end
+
+    private
+
+    def sift_down(i)
+      n = @a.size
+      loop do
+        l = 2 * i + 1
+        r = 2 * i + 2
+        smallest = i
+        smallest = l if l < n && @a[l].deadline < @a[smallest].deadline
+        smallest = r if r < n && @a[r].deadline < @a[smallest].deadline
+        break if smallest == i
+        @a[i], @a[smallest] = @a[smallest], @a[i]
+        i = smallest
+      end
+    end
+  end
+end

data/lib/winloop/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Winloop
+  VERSION = "0.1.0"
+end

data/lib/winloop.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "winloop/version"
+
+# winloop — a native Windows (IOCP) Fiber Scheduler for MRI Ruby.
+#
+#   require "winloop"
+#
+#   Winloop.run do
+#     server = TCPServer.new("127.0.0.1", 9292)
+#     loop do
+#       client = server.accept          # io_wait via AFD poll
+#       Fiber.schedule do               # one fiber per connection
+#         while (line = client.gets)    # io_read via recv_nonblock + io_wait
+#           client.write(line)
+#         end
+#         client.close
+#       end
+#     end
+#   end
+#
+# All blocking socket I/O, sleeps, timeouts and Mutex/Queue/Thread#join inside
+# the block run cooperatively on a single thread, driven by one I/O Completion
+# Port. See Winloop::Scheduler for the hook implementations.
+module Winloop
+  class Error < StandardError; end unless const_defined?(:Error)
+
+  # Loaded for its side effect of defining Winloop::Backend + the IO event
+  # constants (READABLE/WRITABLE/PRIORITY). mswin-only.
+  begin
+    require "winloop/winloop"
+  rescue LoadError => e
+    raise LoadError, "winloop's native backend failed to load — winloop needs a " \
+                     "Windows MSVC (mswin) Ruby. (#{e.message})"
+  end
+
+  require_relative "winloop/scheduler"
+
+  module_function
+
+  # True if the IOCP/AFD backend is available on this platform.
+  def supported?
+    const_defined?(:Backend)
+  end
+
+  # Install a fresh Winloop::Scheduler on the current thread, run `block` inside
+  # a non-blocking fiber, drive the event loop until every scheduled fiber has
+  # finished, and return the block's value.
+  #
+  # Nesting is not supported; if a scheduler is already installed, the block is
+  # simply scheduled on it.
+  def run
+    raise ArgumentError, "Winloop.run requires a block" unless block_given?
+
+    # Already inside a scheduler (e.g. a nested Winloop.run within a fiber): just
+    # run the block here — blocking operations already cooperate with that loop.
+    return yield if Fiber.scheduler
+
+    scheduler = Scheduler.new
+    Fiber.set_scheduler(scheduler)
+    result = nil
+    error = nil
+    Fiber.schedule do
+      begin
+        result = yield
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        error = e
+      end
+    end
+    scheduler.close # drives the loop to completion
+    raise error if error
+    result
+  ensure
+    # Detach our (now-closed) scheduler so subsequent ordinary I/O on this
+    # thread doesn't hit a closed backend. Safe here: we are on the main fiber
+    # and close has already returned (the reentrant-close trap only bites when
+    # set_scheduler(nil) is called from *inside* #close during finalization).
+    Fiber.set_scheduler(nil) if Fiber.scheduler.equal?(scheduler)
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: winloop
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leiz
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: |
+  winloop is a Ruby Fiber::Scheduler built on Win32 I/O Completion Ports. It
+  makes ordinary socket I/O, sleeps, timeouts and Mutex/Queue/Thread#join run
+  cooperatively on a single thread — the async-runtime story that has always
+  been weak on Windows, done the way libuv/mio/wepoll do it: readiness over an
+  IOCP via \Device\Afd polling, with recv/send driven by the completion port.
+  Requires a native Windows MSVC (mswin) build of Ruby.
+executables: []
+extensions:
+- ext/winloop/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/winloop/extconf.rb
+- ext/winloop/winloop.c
+- lib/winloop.rb
+- lib/winloop/scheduler.rb
+- lib/winloop/version.rb
+homepage: https://github.com/leiz/winloop
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/leiz/winloop
+  source_code_uri: https://github.com/leiz/winloop
+  changelog_uri: https://github.com/leiz/winloop/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A native Windows (IOCP) Fiber Scheduler for MRI Ruby.
+test_files: []