zuvloop 0.0.1__tar.gz → 0.0.2__tar.gz

{zuvloop-0.0.1 → zuvloop-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: zuvloop
-Version: 0.0.1
+Version: 0.0.2
 Summary: A libuv event loop for asyncio, written in Zig.
 Project-URL: Source, https://github.com/Kludex/zuvloop
 Author-email: Marcelo Trylesinski <marcelotryle@gmail.com>
@@ -59,16 +59,17 @@ Throughput relative to stock asyncio (higher is better), measured with the suite
 
 | Benchmark | asyncio | uvloop | zuvloop |
 | --- | ---: | ---: | ---: |
-| `call_soon` | 2.69M/s | 4.69M/s | **5.91M/s** |
-| `call_soon` with arguments | 2.43M/s | 3.87M/s | **6.47M/s** |
-| timer schedule + cancel | 1.58M/s | 2.62M/s | **9.55M/s** |
-| bulk stream | 8.4 GiB/s | 8.5 GiB/s | **10.2 GiB/s** |
-| echo round trips, 1 KiB | 39.0k/s | 56.8k/s | **58.5k/s** |
-| uvicorn, plaintext | 55.3k req/s | 71.9k req/s | **75.9k req/s** |
-| uvicorn, 10 KiB body | 52.6k req/s | 68.7k req/s | **73.6k req/s** |
-| aiohttp server | 49.0k req/s | 59.8k req/s | **60.6k req/s** |
-| aiohttp client | 13.2k req/s | 16.2k req/s | **16.9k req/s** |
-| `getaddrinfo`, numeric host | 28.5k/s | 1.57M/s | **1.90M/s** |
+| `call_soon` | 2.59M/s | 5.66M/s | **5.90M/s** |
+| `call_soon` with arguments | 2.45M/s | 3.55M/s | **6.36M/s** |
+| `call_soon_threadsafe` | 0.44M/s | 5.06M/s | **6.51M/s** |
+| timer schedule + cancel | 1.55M/s | 2.57M/s | **9.58M/s** |
+| bulk stream | 8.6 GiB/s | 9.0 GiB/s | **10.7 GiB/s** |
+| echo round trips, 1 KiB | 38.4k/s | 53.0k/s | **58.4k/s** |
+| uvicorn, plaintext | 54.0k req/s | 70.5k req/s | **76.7k req/s** |
+| uvicorn, 10 KiB body | 51.6k req/s | 69.5k req/s | **74.2k req/s** |
+| aiohttp server | 48.8k req/s | 61.0k req/s | **62.6k req/s** |
+| aiohttp client | 13.4k req/s | 16.6k req/s | **16.9k req/s** |
+| `getaddrinfo`, numeric host | 28.3k/s | 1.58M/s | **1.91M/s** |
 
 Curious how? The [architecture docs](https://zuvloop.marcelotryle.com) explain the design:
 argument storage inside handles (no tuple per callback), a native timer heap behind a single
@@ -121,8 +122,9 @@ That's it. That's the migration. 🎉
 ## Observability
 
 zuvloop emits plain OpenTelemetry. The only runtime dependency is `opentelemetry-api` — not the
-SDK, nothing vendor-specific. Until your application installs a provider, the instruments are
-no-ops and cost nothing.
+SDK, nothing vendor-specific. Configure providers before starting the loop; zuvloop checks for them
+at each `run_forever()` entry. Until then the instruments are no-ops and slow-callback timing stays
+off.
 
 Anything that speaks OpenTelemetry can collect it. For example, with
 <a href="https://logfire.pydantic.dev" target="_blank">Logfire</a>:
@@ -192,10 +194,12 @@ returns and nothing else. A loop that needs a controllable clock should schedule
 explicitly.
 
 Also not implemented: `sendfile()` and `sock_sendfile()` raise `NotImplementedError`. Handles
-returned by `call_soon` and `call_later` implement the `asyncio.Handle` and
-`asyncio.TimerHandle` interfaces but are not instances of those classes; `call_soon_threadsafe`
-does return a real `asyncio.Handle`, because 3.14 requires cancelling one from another thread to
-block until a callback that has already started finishes.
+returned by `call_soon` implement the `asyncio.Handle` interface but are not instances of it:
+the base class is 56 bytes of storage such a handle never writes, measured at 2% of `call_soon`,
+which is the object the loop allocates more often than any other. `call_later` and `call_at`
+do return real `asyncio.TimerHandle` instances, so they order and compare by deadline, and
+`call_soon_threadsafe` returns a real `asyncio.Handle`, because 3.14 requires cancelling one
+from another thread to block until a callback that has already started finishes.
 
 ## Development
 

{zuvloop-0.0.1 → zuvloop-0.0.2}/README.md

@@ -35,16 +35,17 @@ Throughput relative to stock asyncio (higher is better), measured with the suite
 
 | Benchmark | asyncio | uvloop | zuvloop |
 | --- | ---: | ---: | ---: |
-| `call_soon` | 2.69M/s | 4.69M/s | **5.91M/s** |
-| `call_soon` with arguments | 2.43M/s | 3.87M/s | **6.47M/s** |
-| timer schedule + cancel | 1.58M/s | 2.62M/s | **9.55M/s** |
-| bulk stream | 8.4 GiB/s | 8.5 GiB/s | **10.2 GiB/s** |
-| echo round trips, 1 KiB | 39.0k/s | 56.8k/s | **58.5k/s** |
-| uvicorn, plaintext | 55.3k req/s | 71.9k req/s | **75.9k req/s** |
-| uvicorn, 10 KiB body | 52.6k req/s | 68.7k req/s | **73.6k req/s** |
-| aiohttp server | 49.0k req/s | 59.8k req/s | **60.6k req/s** |
-| aiohttp client | 13.2k req/s | 16.2k req/s | **16.9k req/s** |
-| `getaddrinfo`, numeric host | 28.5k/s | 1.57M/s | **1.90M/s** |
+| `call_soon` | 2.59M/s | 5.66M/s | **5.90M/s** |
+| `call_soon` with arguments | 2.45M/s | 3.55M/s | **6.36M/s** |
+| `call_soon_threadsafe` | 0.44M/s | 5.06M/s | **6.51M/s** |
+| timer schedule + cancel | 1.55M/s | 2.57M/s | **9.58M/s** |
+| bulk stream | 8.6 GiB/s | 9.0 GiB/s | **10.7 GiB/s** |
+| echo round trips, 1 KiB | 38.4k/s | 53.0k/s | **58.4k/s** |
+| uvicorn, plaintext | 54.0k req/s | 70.5k req/s | **76.7k req/s** |
+| uvicorn, 10 KiB body | 51.6k req/s | 69.5k req/s | **74.2k req/s** |
+| aiohttp server | 48.8k req/s | 61.0k req/s | **62.6k req/s** |
+| aiohttp client | 13.4k req/s | 16.6k req/s | **16.9k req/s** |
+| `getaddrinfo`, numeric host | 28.3k/s | 1.58M/s | **1.91M/s** |
 
 Curious how? The [architecture docs](https://zuvloop.marcelotryle.com) explain the design:
 argument storage inside handles (no tuple per callback), a native timer heap behind a single
@@ -97,8 +98,9 @@ That's it. That's the migration. 🎉
 ## Observability
 
 zuvloop emits plain OpenTelemetry. The only runtime dependency is `opentelemetry-api` — not the
-SDK, nothing vendor-specific. Until your application installs a provider, the instruments are
-no-ops and cost nothing.
+SDK, nothing vendor-specific. Configure providers before starting the loop; zuvloop checks for them
+at each `run_forever()` entry. Until then the instruments are no-ops and slow-callback timing stays
+off.
 
 Anything that speaks OpenTelemetry can collect it. For example, with
 <a href="https://logfire.pydantic.dev" target="_blank">Logfire</a>:
@@ -168,10 +170,12 @@ returns and nothing else. A loop that needs a controllable clock should schedule
 explicitly.
 
 Also not implemented: `sendfile()` and `sock_sendfile()` raise `NotImplementedError`. Handles
-returned by `call_soon` and `call_later` implement the `asyncio.Handle` and
-`asyncio.TimerHandle` interfaces but are not instances of those classes; `call_soon_threadsafe`
-does return a real `asyncio.Handle`, because 3.14 requires cancelling one from another thread to
-block until a callback that has already started finishes.
+returned by `call_soon` implement the `asyncio.Handle` interface but are not instances of it:
+the base class is 56 bytes of storage such a handle never writes, measured at 2% of `call_soon`,
+which is the object the loop allocates more often than any other. `call_later` and `call_at`
+do return real `asyncio.TimerHandle` instances, so they order and compare by deadline, and
+`call_soon_threadsafe` returns a real `asyncio.Handle`, because 3.14 requires cancelling one
+from another thread to block until a callback that has already started finishes.
 
 ## Development
 

{zuvloop-0.0.1 → zuvloop-0.0.2}/build.zig

@@ -55,7 +55,12 @@ const uv_linux = [_][]const u8{
 };
 
 pub fn build(b: *std.Build) void {
-    const target = b.standardTargetOptions(.{});
+    // A wheel is built on whatever machine the job landed on, and without a
+    // baseline default Zig compiles for that machine's CPU: the published
+    // manylinux wheel carried AVX2, BMI and MOVBE, so it would raise SIGILL on
+    // anything older than Haswell. Which instructions it needed depended on the
+    // runner. `-Dcpu=native` is still there for a build meant for one machine.
+    const target = b.standardTargetOptions(.{ .default_target = .{ .cpu_model = .baseline } });
     const optimize = b.standardOptimizeOption(.{});
 
     // hatch-ziglang passes the building interpreter through the environment, so a

{zuvloop-0.0.1 → zuvloop-0.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "zuvloop"
-version = "0.0.1"
+version = "0.0.2"
 description = "A libuv event loop for asyncio, written in Zig."
 readme = "README.md"
 requires-python = ">=3.14"

{zuvloop-0.0.1 → zuvloop-0.0.2}/zig/addr.zig

@@ -23,12 +23,16 @@ pub const AF_INET: c_int = posix.AF.INET;
 pub const AF_INET6: c_int = posix.AF.INET6;
 pub const AF_UNIX: c_int = posix.AF.UNIX;
 
+const UN_BASE = @offsetOf(posix.sockaddr.un, "path");
+
 fn tupleItem(t: *py.Object, i: c.Py_ssize_t) py.Error!*py.Object {
     return c.PyTuple_GetItem(t, i) orelse py.Error.Python;
 }
 
-/// Fills `out` from `(host, port[, flowinfo, scopeid])` or a filesystem path.
-pub fn fromPython(family: c_int, address: *py.Object, out: *Storage) py.Error!void {
+/// Fills `out` from `(host, port[, flowinfo, scopeid])` or a filesystem path,
+/// returning its length - the only thing that tells an abstract `AF_UNIX` name
+/// from a shorter one padded with zeros.
+pub fn fromPython(family: c_int, address: *py.Object, out: *Storage) py.Error!c_int {
     out.* = .{};
     if (family == AF_UNIX) {
         var path: [*c]const u8 = undefined;
@@ -45,7 +49,7 @@ pub fn fromPython(family: c_int, address: *py.Object, out: *Storage) py.Error!vo
         if (len >= un.path.len) return py.errValue("AF_UNIX path too long");
         un.family = @intCast(AF_UNIX);
         @memcpy(un.path[0..@intCast(len)], path[0..@intCast(len)]);
-        return;
+        return @intCast(UN_BASE + @as(usize, @intCast(len)));
     }
 
     if (c.PyTuple_Check(address) == 0) return py.errType("address must be a tuple");
@@ -53,7 +57,14 @@ pub fn fromPython(family: c_int, address: *py.Object, out: *Storage) py.Error!vo
     if (size < 2) return py.errType("address tuple must be (host, port)");
 
     const host_obj = try tupleItem(address, 0);
-    const port = try py.asCInt(try tupleItem(address, 1));
+    // Read wide and saturating, then narrow: converting to `c_int` first would
+    // refuse a port above `INT_MAX` with an error about the width of the type,
+    // before the range check below ever saw it.
+    const port_value = try py.asIsizeClamped(try tupleItem(address, 1));
+    // `uv_ip4_addr` stores `htons(port)`, which truncates rather than complains:
+    // a port of 70000 would quietly address 4464. The standard library rejects it.
+    if (port_value < 0 or port_value > 65535) return py.errOverflow("port must be 0-65535");
+    const port: c_int = @intCast(port_value);
 
     var host_buf: [256]u8 = undefined;
     const host: [*:0]const u8 = blk: {
@@ -71,10 +82,11 @@ pub fn fromPython(family: c_int, address: *py.Object, out: *Storage) py.Error!vo
         try py.errUvIfNeg(uv.uv_ip6_addr(host, port, sin6));
         if (size >= 3) sin6.flowinfo = @intCast(try py.asCInt(try tupleItem(address, 2)));
         if (size >= 4) sin6.scope_id = @intCast(try py.asCInt(try tupleItem(address, 3)));
-        return;
+        return @sizeOf(posix.sockaddr.in6);
     }
     const sin: *posix.sockaddr.in = @ptrCast(out);
     try py.errUvIfNeg(uv.uv_ip4_addr(host, port, sin));
+    return @sizeOf(posix.sockaddr.in);
 }
 
 /// Builds the tuple `socket.getsockname()` would return for `sa`.
@@ -105,3 +117,38 @@ pub fn toPython(sa: *const posix.sockaddr) py.Error!*py.Object {
         @as(c_uint, sin6.scope_id),
     ) orelse py.Error.Python;
 }
+
+/// Whether two addresses name the same endpoint.
+///
+/// Only the fields that identify the peer are read: a byte comparison would trip
+/// over padding, and over the `sin_len` the BSDs carry.
+/// The bytes that name an `AF_UNIX` socket, as the kernel distinguishes them: an
+/// abstract name is as long as the reported length says, so `\0foo` and `\0foo\0`
+/// differ, while a pathname ends at its terminator - which the two sides need not
+/// agree on counting.
+fn unixName(sa: *const posix.sockaddr, len: c_int) []const u8 {
+    const un: *const posix.sockaddr.un = @ptrCast(@alignCast(sa));
+    if (len <= UN_BASE) return un.path[0..0];
+    const n = @min(@as(usize, @intCast(len)) - UN_BASE, un.path.len);
+    if (un.path[0] == 0) return un.path[0..n];
+    return un.path[0 .. std.mem.indexOfScalar(u8, un.path[0..n], 0) orelse n];
+}
+
+pub fn same(a: *const posix.sockaddr, a_len: c_int, b: *const posix.sockaddr, b_len: c_int) bool {
+    if (a.family != b.family) return false;
+    if (a.family == AF_UNIX) return std.mem.eql(u8, unixName(a, a_len), unixName(b, b_len));
+    if (a.family == AF_INET) {
+        const x: *const posix.sockaddr.in = @ptrCast(@alignCast(a));
+        const y: *const posix.sockaddr.in = @ptrCast(@alignCast(b));
+        return x.port == y.port and x.addr == y.addr;
+    }
+    if (a.family == AF_INET6) {
+        const x: *const posix.sockaddr.in6 = @ptrCast(@alignCast(a));
+        const y: *const posix.sockaddr.in6 = @ptrCast(@alignCast(b));
+        if (x.port != y.port or !std.mem.eql(u8, &x.addr, &y.addr)) return false;
+        // asyncio compares tuples, so it wants the scope stated rather than
+        // treating a zero as a wildcard.
+        return x.scope_id == y.scope_id;
+    }
+    return false;
+}

{zuvloop-0.0.1 → zuvloop-0.0.2}/zig/collections.zig

@@ -119,13 +119,30 @@ pub const Timers = struct {
     }
 
     /// Drops cancelled entries once they dominate the heap.
-    pub fn compact(self: *Timers, isCancelled: *const fn (*py.Object) bool) void {
+    /// Drops cancelled entries and restores the heap.
+    ///
+    /// The handles are released only once the heap is whole again. Releasing one
+    /// runs its arguments' finalizers, and a finalizer calling `call_later`
+    /// reaches `push`, which writes at `items[len]` and sifts - so a release from
+    /// inside the pass would shuffle slots the pass has already moved, and one
+    /// from inside the array would land on an entry not yet released. Which is
+    /// also why the doomed handles are copied out rather than parked in the tail.
+    pub fn compact(self: *Timers, shouldDrop: *const fn (*py.Object) bool) void {
+        // Sized by the heap rather than by `cancelled`, which is a hint and not a
+        // guarantee: `Handle.cancel` only reports to the loop while it still has
+        // one, so an entry can be cancelled without ever being counted. Nowhere
+        // to set them aside means nothing can be released, so the heap is left
+        // exactly as it was - count included - for the next cancellation to retry.
+        const doomed = alloc.alloc(*py.Object, self.len) catch return;
+        defer alloc.free(doomed);
+        var dropped: usize = 0;
         var write: usize = 0;
         var read: usize = 0;
         while (read < self.len) : (read += 1) {
             const entry = self.items[read];
-            if (isCancelled(entry.handle)) {
-                py.decref(entry.handle);
+            if (shouldDrop(entry.handle)) {
+                doomed[dropped] = entry.handle;
+                dropped += 1;
             } else {
                 self.items[write] = entry;
                 write += 1;
@@ -133,12 +150,14 @@ pub const Timers = struct {
         }
         self.len = write;
         self.cancelled = 0;
-        if (write < 2) return;
-        var i = write / 2;
-        while (i > 0) {
-            i -= 1;
-            self.siftDown(i);
+        if (write >= 2) {
+            var i = write / 2;
+            while (i > 0) {
+                i -= 1;
+                self.siftDown(i);
+            }
         }
+        for (doomed[0..dropped]) |handle| py.decref(handle);
     }
 
     fn grow(self: *Timers) error{OutOfMemory}!void {

{zuvloop-0.0.1 → zuvloop-0.0.2}/zig/datagram.zig

@@ -215,7 +215,11 @@ fn onRecv(
     };
     defer py.decref(data);
     const sender = addr.toPython(from.?) catch {
-        c.PyErr_Clear();
+        // The datagram cannot be delivered without naming its sender, and a
+        // receive failure is what `error_received` exists to report.
+        const exc = c.PyErr_GetRaisedException() orelse return;
+        defer py.decref(exc);
+        callInContext(self, self.cb_error_received, &.{exc});
         return;
     };
     defer py.decref(sender);
@@ -365,16 +369,25 @@ fn sendto(self_obj: *py.Object, args: []const ?*py.Object, nargs: usize, kwnames
         }
     }
     const self = asDatagram(self_obj);
-    if (self.flags & CONN_LOST != 0) return py.noneRef();
-    if (self.flags & CLOSING != 0) return py.errRuntime("Cannot call sendto() after close()");
 
     const target = if (address) |a| (if (py.isNone(a)) null else address) else null;
     var dest: addr.Storage = .{};
     var dest_ptr: ?*const std.posix.sockaddr = null;
     if (target) |t| {
-        if (self.flags & CONNECTED != 0) return py.errValue("Transport is connected; sendto() takes no address");
-        try addr.fromPython(self.family, t, &dest);
-        dest_ptr = dest.ptr();
+        const dest_len = try addr.fromPython(self.family, t, &dest);
+        if (self.flags & CONNECTED != 0) {
+            // Naming the peer is allowed, as it is for asyncio; naming anything
+            // else is not.
+            var peer: addr.Storage = .{};
+            var len: c_int = @sizeOf(addr.Storage);
+            if (uv.uv_udp_getpeername(self.udp(), peer.ptr(), &len) < 0 or
+                !addr.same(dest.constPtr(), dest_len, peer.constPtr(), len))
+            {
+                return py.errValue("Transport is connected; sendto() takes no address but the peer's");
+            }
+        } else {
+            dest_ptr = dest.ptr();
+        }
     } else if (self.flags & CONNECTED == 0) {
         return py.errValue("sendto() requires an address on an unconnected transport");
     }
@@ -382,6 +395,11 @@ fn sendto(self_obj: *py.Object, args: []const ?*py.Object, nargs: usize, kwnames
     var view: c.Py_buffer = undefined;
     if (c.PyObject_GetBuffer(args[0].?, &view, c.PyBUF_SIMPLE) < 0) return py.Error.Python;
     defer c.PyBuffer_Release(&view);
+
+    // A closing endpoint drops the datagram, as asyncio does - but the argument
+    // errors above still raise there, which is why they all come first.
+    if (self.flags & (CONN_LOST | CLOSING) != 0) return py.noneRef();
+
     const buf = uv.Buf{ .base = @ptrCast(view.buf), .len = @intCast(view.len) };
 
     if (self.write_buffer_size == 0) {
@@ -509,6 +527,29 @@ fn adoptSocketView(self_obj: *py.Object, view: *py.Object) py.Error!*py.Object {
     return py.noneRef();
 }
 
+/// `pause_reading()`: stop delivering datagrams until reading resumes.
+///
+/// A datagram endpoint that is not reading leaves what arrives in the socket's
+/// receive buffer, and the kernel drops from there once it fills. That is what
+/// asyncio's does too; uvloop's has no such method at all.
+fn pauseReading(self_obj: *py.Object) py.Error!*py.Object {
+    const self = asDatagram(self_obj);
+    if (self.flags & CLOSING != 0) return py.errRuntime("Cannot pause_reading() after close()");
+    if (self.flags & READING != 0) {
+        _ = uv.uv_udp_recv_stop(self.udp());
+        self.flags &= ~READING;
+    }
+    return py.noneRef();
+}
+
+/// `resume_reading()`: deliver datagrams again.
+fn resumeReading(self_obj: *py.Object) py.Error!*py.Object {
+    const self = asDatagram(self_obj);
+    if (self.flags & CLOSING != 0) return py.errRuntime("Cannot resume_reading() after close()");
+    try startReceiving(self);
+    return py.noneRef();
+}
+
 fn startReceivingMethod(self_obj: *py.Object) py.Error!*py.Object {
     const self = asDatagram(self_obj);
     startReceiving(self) catch {
@@ -652,6 +693,8 @@ var methods = [_]c.PyMethodDef{
     py.methodNoArgs("get_protocol", getProtocol, "Return the current protocol."),
     py.methodO("set_protocol", setProtocol, "Replace the current protocol."),
     py.methodO("_adopt_socket_view", adoptSocketView, "Track the socket object mirroring libuv's descriptor."),
+    py.methodNoArgs("pause_reading", pauseReading, "Stop delivering datagrams."),
+    py.methodNoArgs("resume_reading", resumeReading, "Deliver datagrams again."),
     py.methodNoArgs("_start_receiving", startReceivingMethod, "Begin delivering datagrams."),
     py.methodKw("sendto", sendto, "Send a datagram to an address."),
     py.methodNoArgs("get_write_buffer_size", getWriteBufferSize, "Return the number of bytes queued."),

{zuvloop-0.0.1 → zuvloop-0.0.2}/zig/dns.zig

@@ -152,10 +152,72 @@ fn settle(future: *py.Object, method: ?*py.Object, value: *py.Object) void {
     py.decref(res);
 }
 
-fn failFuture(future: *py.Object, status: c_int) void {
+/// The member if this platform has it, and a stand-in if it does not: glibc
+/// carries no `EAI_BADHINTS` or `EAI_PROTOCOL`, and the codes are not the same
+/// numbers across platforms either.
+inline fn eai(comptime name: [:0]const u8, comptime fallback: std.c.EAI) std.c.EAI {
+    return if (@hasField(std.c.EAI, name)) @field(std.c.EAI, name) else fallback;
+}
+
+/// libuv reports resolver failures with codes of its own; `socket.gaierror`
+/// carries the platform's `EAI_*`, which is what callers written against the
+/// standard library compare against. Anything that is not a resolver failure -
+/// a cancellation, an out-of-memory - is left to `OSError`.
+fn resolverError(status: c_int) ?std.c.EAI {
+    return switch (status) {
+        uv.EAI_ADDRFAMILY => eai("ADDRFAMILY", .FAIL),
+        uv.EAI_AGAIN => .AGAIN,
+        uv.EAI_BADFLAGS => .BADFLAGS,
+        uv.EAI_BADHINTS => eai("BADHINTS", .FAIL),
+        uv.EAI_FAIL => .FAIL,
+        uv.EAI_FAMILY => .FAMILY,
+        uv.EAI_MEMORY => .MEMORY,
+        uv.EAI_NODATA => eai("NODATA", .NONAME),
+        uv.EAI_NONAME => .NONAME,
+        uv.EAI_OVERFLOW => eai("OVERFLOW", .FAIL),
+        uv.EAI_PROTOCOL => eai("PROTOCOL", .FAIL),
+        uv.EAI_SERVICE => .SERVICE,
+        uv.EAI_SOCKTYPE => .SOCKTYPE,
+        else => null,
+    };
+}
+
+/// Builds the exception the standard library would have raised for `status`.
+fn resolverException(status: c_int) ?*py.Object {
+    if (resolverError(status)) |code| {
+        return c.PyObject_CallFunction(gaierror, "is", @intFromEnum(code), std.c.gai_strerror(code));
+    }
     var buf: [128]u8 = undefined;
     const msg = uv.strerror(status, &buf);
-    const exc = c.PyObject_CallFunction(gaierror, "is", @as(c_int, status), msg.ptr) orelse {
+    return c.PyObject_CallFunction(@ptrCast(c.PyExc_OSError), "is", uv.toErrno(status), msg.ptr);
+}
+
+/// Raises `socket.gaierror` for a code the platform's resolver produced itself.
+fn raisePlatformError(code: std.c.EAI) py.Error {
+    // `EAI_SYSTEM` says only that the real error is in `errno`, so the standard
+    // library reports that instead - `set_gaierror` in CPython's socketmodule
+    // hands it straight to `PyErr_SetFromErrno`. Windows has no such code.
+    if (@hasField(std.c.EAI, "SYSTEM") and code == eai("SYSTEM", .FAIL)) {
+        _ = c.PyErr_SetFromErrno(@ptrCast(c.PyExc_OSError));
+        return py.Error.Python;
+    }
+    const exc = c.PyObject_CallFunction(gaierror, "is", @intFromEnum(code), std.c.gai_strerror(code)) orelse
+        return py.Error.Python;
+    c.PyErr_SetRaisedException(exc);
+    return py.Error.Python;
+}
+
+/// Raises it, for the paths that report synchronously rather than through a future.
+/// `PyErr_SetRaisedException` takes the reference, and needs no separate type -
+/// `PyObject_Type` would hand back one more to own.
+fn raiseResolverError(status: c_int) py.Error {
+    const exc = resolverException(status) orelse return py.Error.Python;
+    c.PyErr_SetRaisedException(exc);
+    return py.Error.Python;
+}
+
+fn failFuture(future: *py.Object, status: c_int) void {
+    const exc = resolverException(status) orelse {
         py.writeUnraisable(future);
         return;
     };
@@ -370,6 +432,35 @@ pub fn getaddrinfo(self_obj: *py.Object, args: []const ?*py.Object) py.Error!*py
     hints.protocol = try py.asCInt(args[4].?);
     hints.flags = @bitCast(@as(u32, @bitCast(try py.asCInt(args[5].?))));
 
+    // libuv refuses this pair outright, before any resolver sees it, and reports
+    // it as EINVAL. The resolver the standard library reaches would have answered
+    // "neither node nor service", which is what callers are written to expect.
+    if (host == null and service == null) return raiseResolverError(uv.EAI_NONAME);
+
+    // libuv runs every hostname through IDNA, which rejects an empty one, so `""`
+    // can never reach a resolver that way. The platforms disagree about what it
+    // means - BSD reads it as the null host, glibc as a name it cannot find - and
+    // matching `socket.getaddrinfo` means letting the platform answer rather than
+    // picking one.
+    //
+    // Nothing is resolved here, but this does enter libc on the loop thread, and
+    // the first call in a process pays for the resolver's own initialization:
+    // measured on macOS at 1.5ms for a numeric service and 2.3ms for a name,
+    // then under a microsecond for every call after it. `resolveNumeric` pays the
+    // same initialization on the main path, so moving this one to a threadpool
+    // would not buy a loop that never waits for the resolver to wake up.
+    if (host) |name| if (name[0] == 0) {
+        var res: ?*std.c.addrinfo = null;
+        const rc = std.c.getaddrinfo(name, service, &hints, &res);
+        if (rc != @as(std.c.EAI, @enumFromInt(0))) return raisePlatformError(rc);
+        defer if (res) |first| std.c.freeaddrinfo(first);
+        const list = try buildResults(res);
+        defer py.decref(list);
+        const future = c.PyObject_CallMethodNoArgs(@ptrCast(loop), str_create_future) orelse return py.Error.Python;
+        settle(future, str_set_result, list);
+        return future;
+    };
+
     if (resolveLiteral(&hints, host, service) orelse resolveNumeric(&hints, host, service)) |list| {
         defer py.decref(list);
         const future = c.PyObject_CallMethodNoArgs(@ptrCast(loop), str_create_future) orelse return py.Error.Python;
@@ -385,7 +476,8 @@ pub fn getaddrinfo(self_obj: *py.Object, args: []const ?*py.Object) py.Error!*py
     const req_host: ?[*:0]const u8 = if (host == null) null else @ptrCast(&req.host);
     const req_service: ?[*:0]const u8 = if (service == null) null else @ptrCast(&req.service);
 
-    try py.errUvIfNeg(uv.uv_getaddrinfo(loop.state().uvloop, req.addrReq(), onAddrInfo, req_host, req_service, &req.hints));
+    const status = uv.uv_getaddrinfo(loop.state().uvloop, req.addrReq(), onAddrInfo, req_host, req_service, &req.hints);
+    if (status < 0) return raiseResolverError(status);
     return py.newref(req.future.?).?;
 }
 
@@ -396,12 +488,19 @@ pub fn getnameinfo(self_obj: *py.Object, args: []const ?*py.Object) py.Error!*py
     try loopmod.checkClosed(loop.state());
 
     var storage: addr.Storage = .{};
-    try addr.fromPython(0, args[0].?, &storage);
+    _ = addr.fromPython(0, args[0].?, &storage) catch |e| {
+        // Only the host is the resolver's to report; a bad tuple or port keeps
+        // its own exception, and those are not `OSError`.
+        if (c.PyErr_ExceptionMatches(@ptrCast(c.PyExc_OSError)) == 0) return e;
+        c.PyErr_Clear();
+        return raisePlatformError(eai("NONAME", .FAIL));
+    };
     const flags = try py.asCInt(args[1].?);
 
     const req = try allocRequest(loop, .getnameinfo);
     errdefer freeRequest(req, .getnameinfo);
-    try py.errUvIfNeg(uv.uv_getnameinfo(loop.state().uvloop, req.nameReq(), onNameInfo, storage.constPtr(), flags));
+    const status = uv.uv_getnameinfo(loop.state().uvloop, req.nameReq(), onNameInfo, storage.constPtr(), flags);
+    if (status < 0) return raiseResolverError(status);
     return py.newref(req.future.?).?;
 }