std.Io: move netReceive to become an Operation #31089

andrewrk commented 2026年02月02日 09:08:26 +01:00

Notably, the timeout becomes provided by the general-purpose Batch API rather than being special-purposed.

Also implements the operation for Windows in std.Io.Threaded as well as implementing netSend for Windows.

Release Notes

Windows Applications and ws2_32.dll Dependency

Due to the way std.Io currently works, Windows applications will be more likely to inadvertently drag in a dependency on networking, and therefore ws2_32.dll even if no networking functionality is used. There are ways to work around this problem:

• Use std.options to networking to false in the root source file. This causes all std.Io networking functions to return error.NetworkDown and prevents accidental dependency on ws2_32.dll.
• Explicitly add the -lws2_32 dependency via CLI or linkSystemLibrary in build.zig script.
• Avoid taking a detour through object file format by compiling Zig source files directly into executables (related: #31425)

This is a breaking change from 0.15.x. This has the same root cause as #31421 but it's extra problematic due to the ws2_32.dll dependency.

In the future, here are some more options to possibly explore:

• networking via bypassing the Winsock API and using \Device\Afd directly (see #31131)
• enhanced frontend compiler optimizations leading to pruning unused DLL dependencies, including in Debug mode.

std.Io.operateTimeout

The function std.Io.operateTimeout is provided to conveniently perform any single Io.Operation with ability to fail with error.Timeout after a specified duration or at a specified timestamp. This function is implemented via the lower-level Io.Batch.awaitConcurrent API.

Follow-up Work

• std.Io.Uring Batch implementation
• std.Io.Dispatch implementation
• move almost all the file and networking functionality to be based on Operation and support Batch

Notably, the timeout becomes provided by the general-purpose Batch API rather than being special-purposed. Also implements the operation for Windows in `std.Io.Threaded` as well as implementing `netSend` for Windows. ## Release Notes ### Windows Applications and ws2_32.dll Dependency Due to the way `std.Io` currently works, Windows applications will be more likely to inadvertently drag in a dependency on networking, and therefore `ws2_32.dll` even if no networking functionality is used. There are ways to work around this problem: * Use `std.options` to `networking` to `false` in the root source file. This causes all `std.Io` networking functions to return `error.NetworkDown` and prevents accidental dependency on `ws2_32.dll`. * Explicitly add the `-lws2_32` dependency via CLI or `linkSystemLibrary` in build.zig script. * Avoid taking a detour through object file format by compiling Zig source files directly into executables (related: #31425) This is a breaking change from 0.15.x. This has the same root cause as #31421 but it's extra problematic due to the ws2_32.dll dependency. In the future, here are some more options to possibly explore: * networking via bypassing the Winsock API and using \Device\Afd directly (see #31131) * enhanced frontend compiler optimizations leading to pruning unused DLL dependencies, including in Debug mode. ### `std.Io.operateTimeout` The function `std.Io.operateTimeout` is provided to conveniently perform any single `Io.Operation` with ability to fail with `error.Timeout` after a specified duration or at a specified timestamp. This function is implemented via the lower-level `Io.Batch.awaitConcurrent` API. ## Follow-up Work * std.Io.Uring Batch implementation * std.Io.Dispatch implementation * move almost all the file and networking functionality to be based on Operation and support Batch

tobiaskohlbau commented 2026年02月24日 18:20:24 +01:00

Is this blocked on something?
As far as I understand this needs a rebase and should be fine to be merged. If you don't have time to work on this I could create a new MR with only !31089 (commit ba6a8b0c4e) in it.

I've rebased your commit onto the latest master see diff

Feel free to pull in these changes.

Is this blocked on something? As far as I understand this needs a rebase and should be fine to be merged. If you don't have time to work on this I could create a new MR with only https://codeberg.org/ziglang/zig/pulls/31089/commits/ba6a8b0c4e7cb91045a5dba44ff62b419ab2f5c8 in it. I've rebased your commit onto the latest master see [diff](https://codeberg.org/ziglang/zig/compare/master...tobiaskohlbau/zig:push-rwzrxnrzrmot) Feel free to pull in these changes.

andrewrk commented 2026年02月25日 19:28:58 +01:00

Yeah it needs:

• #31202 or some other test coverage added for std.Io.Evented.
• corresponding changes in std.Io.Dispatch and std.Io.Uring
• testing, including making sure the new API remains syscall-optimal for e.g. DNS resolution

Yeah it needs: * https://codeberg.org/ziglang/zig/issues/31202 or some other test coverage added for std.Io.Evented. * corresponding changes in std.Io.Dispatch and std.Io.Uring * testing, including making sure the new API remains syscall-optimal for e.g. DNS resolution

tobiaskohlbau commented 2026年02月25日 19:47:10 +01:00

Thanks for the clarification. I'm afraid that's a bit outside my expertise and therefore I'm unable to help any further.

But still I'm looking forward to it :)

Thanks for the clarification. I'm afraid that's a bit outside my expertise and therefore I'm unable to help any further. But still I'm looking forward to it :)

kristoff commented 2026年03月06日 16:25:21 +01:00

I was able to get the awebo client to build and successfully perform a call with this patch:

diff --git a/lib/std/Io/Threaded.zig b/lib/std/Io/Threaded.zig
index 1486f0b8ff..751ac8023e 100644
--- a/lib/std/Io/Threaded.zig
+++ b/lib/std/Io/Threaded.zig
@@ -12937,13 +12937,81 @@ fn netSendWindows(
 messages: []net.OutgoingMessage,
 flags: net.SendFlags,
 ) struct { ?net.Socket.SendError, usize } {
- if (!have_networking) return .{ error.NetworkDown, 0 };
- const t: *Threaded = @ptrCast(@alignCast(userdata));
- _ = t;
- _ = handle;
- _ = messages;
- _ = flags;
- @panic("TODO netSendWindows");
+ for (messages, 0..) |*m, idx| {
+ netSendWindowsOne(@ptrCast(@alignCast(userdata.?)), handle, m, flags) catch |err| return .{ err, idx };
+ }
+ return .{ null, messages.len };
+}
+
+fn netSendWindowsOne(
+ t: *Threaded,
+ handle: net.Socket.Handle,
+ message: *net.OutgoingMessage,
+ flags: net.SendFlags,
+) net.Socket.SendError!void {
+ if (!have_networking) return error.NetworkDown;
+
+ // Unmapped flags:
+ // confirm: bool = false,
+ // eor: bool = false,
+ // fastopen: bool = false,
+ const windows_flags: u32 =
+ @as(u32, if (flags.oob) ws2_32.MSG.OOB else 0) |
+ @as(u32, if (flags.dont_route) ws2_32.MSG.DONTROUTE else 0);
+
+ var buf: ws2_32.WSABUF = .{
+ .buf = @constCast(message.data_ptr),
+ .len = std.math.cast(u32, message.data_len) orelse return error.MessageOversize,
+ };
+ var n: u32 = undefined;
+ var syscall: Syscall = try .start();
+ var address: WsaAddress = undefined;
+ const address_size = addressToWsa(message.address, &address);
+
+ while (true) {
+ const rc = ws2_32.WSASendTo(
+ handle,
+ (&buf)[0..1],
+ 1,
+ &n,
+ windows_flags,
+ &address.any,
+ address_size,
+ null,
+ null,
+ );
+ if (rc != ws2_32.SOCKET_ERROR) {
+ syscall.finish();
+ return;
+ }
+ switch (ws2_32.WSAGetLastError()) {
+ .EINTR, .ECANCELLED, .E_CANCELLED, .OPERATION_ABORTED => {
+ try syscall.checkCancel();
+ continue;
+ },
+ .NOTINITIALISED => {
+ syscall.finish();
+ try initializeWsa(t);
+ syscall = try .start();
+ continue;
+ },
+
+ .ECONNRESET => return syscall.fail(error.ConnectionResetByPeer),
+ .ENETDOWN => return syscall.fail(error.NetworkDown),
+ .ENETRESET => return syscall.fail(error.ConnectionResetByPeer),
+ .ENOTCONN => return syscall.fail(error.SocketUnconnected),
+ .EFAULT => unreachable, // a pointer is not completely contained in user address space.
+
+ else => |err| {
+ syscall.finish();
+ switch (err) {
+ .EINVAL => return wsaErrorBug(err),
+ .EMSGSIZE => return wsaErrorBug(err),
+ else => return windows.unexpectedWSAError(err),
+ }
+ },
+ }
+ }
 }
 
 fn netSendUnavailable(
diff --git a/lib/std/Io/net.zig b/lib/std/Io/net.zig
index 7a49996ff8..6d5b11e1b1 100644
--- a/lib/std/Io/net.zig
+++ b/lib/std/Io/net.zig
@@ -1117,12 +1117,13 @@ pub const Socket = struct {
 /// * `receiveTimeout`
 pub fn receive(s: *const Socket, io: Io, buffer: []u8) ReceiveError!IncomingMessage {
 var message: IncomingMessage = .init;
- const maybe_err, const count = io.vtable.netReceive(io.userdata, s.handle, (&message)[0..1], buffer, .{}, .none);
- if (maybe_err) |err| switch (err) {
- // No timeout is passed to `netReceieve`, so it must not return timeout related errors.
- error.Timeout => unreachable,
- else => |e| return e,
- };
+ const maybe_err, const count = (try io.operate(.{ .net_receive = .{
+ .socket_handle = s.handle,
+ .message_buffer = (&message)[0..1],
+ .data_buffer = buffer,
+ .flags = .{},
+ } })).net_receive;
+ if (maybe_err) |err| return err;
 assert(1 == count);
 return message;
 }
@@ -1144,7 +1145,7 @@ pub const Socket = struct {
 ) ReceiveTimeoutError!IncomingMessage {
 var message: IncomingMessage = .init;
 const maybe_err, const count = (try io.operateTimeout(.{ .net_receive = .{
- .socket = s.handle,
+ .socket_handle = s.handle,
 .message_buffer = (&message)[0..1],
 .data_buffer = buffer,
 .flags = .{},

I was able to get the awebo client to build and successfully perform a call with this patch: <details> ``` diff --git a/lib/std/Io/Threaded.zig b/lib/std/Io/Threaded.zig index 1486f0b8ff..751ac8023e 100644 --- a/lib/std/Io/Threaded.zig +++ b/lib/std/Io/Threaded.zig @@ -12937,13 +12937,81 @@ fn netSendWindows( messages: []net.OutgoingMessage, flags: net.SendFlags, ) struct { ?net.Socket.SendError, usize } { - if (!have_networking) return .{ error.NetworkDown, 0 }; - const t: *Threaded = @ptrCast(@alignCast(userdata)); - _ = t; - _ = handle; - _ = messages; - _ = flags; - @panic("TODO netSendWindows"); + for (messages, 0..) |*m, idx| { + netSendWindowsOne(@ptrCast(@alignCast(userdata.?)), handle, m, flags) catch |err| return .{ err, idx }; + } + return .{ null, messages.len }; +} + +fn netSendWindowsOne( + t: *Threaded, + handle: net.Socket.Handle, + message: *net.OutgoingMessage, + flags: net.SendFlags, +) net.Socket.SendError!void { + if (!have_networking) return error.NetworkDown; + + // Unmapped flags: + // confirm: bool = false, + // eor: bool = false, + // fastopen: bool = false, + const windows_flags: u32 = + @as(u32, if (flags.oob) ws2_32.MSG.OOB else 0) | + @as(u32, if (flags.dont_route) ws2_32.MSG.DONTROUTE else 0); + + var buf: ws2_32.WSABUF = .{ + .buf = @constCast(message.data_ptr), + .len = std.math.cast(u32, message.data_len) orelse return error.MessageOversize, + }; + var n: u32 = undefined; + var syscall: Syscall = try .start(); + var address: WsaAddress = undefined; + const address_size = addressToWsa(message.address, &address); + + while (true) { + const rc = ws2_32.WSASendTo( + handle, + (&buf)[0..1], + 1, + &n, + windows_flags, + &address.any, + address_size, + null, + null, + ); + if (rc != ws2_32.SOCKET_ERROR) { + syscall.finish(); + return; + } + switch (ws2_32.WSAGetLastError()) { + .EINTR, .ECANCELLED, .E_CANCELLED, .OPERATION_ABORTED => { + try syscall.checkCancel(); + continue; + }, + .NOTINITIALISED => { + syscall.finish(); + try initializeWsa(t); + syscall = try .start(); + continue; + }, + + .ECONNRESET => return syscall.fail(error.ConnectionResetByPeer), + .ENETDOWN => return syscall.fail(error.NetworkDown), + .ENETRESET => return syscall.fail(error.ConnectionResetByPeer), + .ENOTCONN => return syscall.fail(error.SocketUnconnected), + .EFAULT => unreachable, // a pointer is not completely contained in user address space. + + else => |err| { + syscall.finish(); + switch (err) { + .EINVAL => return wsaErrorBug(err), + .EMSGSIZE => return wsaErrorBug(err), + else => return windows.unexpectedWSAError(err), + } + }, + } + } } fn netSendUnavailable( diff --git a/lib/std/Io/net.zig b/lib/std/Io/net.zig index 7a49996ff8..6d5b11e1b1 100644 --- a/lib/std/Io/net.zig +++ b/lib/std/Io/net.zig @@ -1117,12 +1117,13 @@ pub const Socket = struct { /// * `receiveTimeout` pub fn receive(s: *const Socket, io: Io, buffer: []u8) ReceiveError!IncomingMessage { var message: IncomingMessage = .init; - const maybe_err, const count = io.vtable.netReceive(io.userdata, s.handle, (&message)[0..1], buffer, .{}, .none); - if (maybe_err) |err| switch (err) { - // No timeout is passed to `netReceieve`, so it must not return timeout related errors. - error.Timeout => unreachable, - else => |e| return e, - }; + const maybe_err, const count = (try io.operate(.{ .net_receive = .{ + .socket_handle = s.handle, + .message_buffer = (&message)[0..1], + .data_buffer = buffer, + .flags = .{}, + } })).net_receive; + if (maybe_err) |err| return err; assert(1 == count); return message; } @@ -1144,7 +1145,7 @@ pub const Socket = struct { ) ReceiveTimeoutError!IncomingMessage { var message: IncomingMessage = .init; const maybe_err, const count = (try io.operateTimeout(.{ .net_receive = .{ - .socket = s.handle, + .socket_handle = s.handle, .message_buffer = (&message)[0..1], .data_buffer = buffer, .flags = .{}, ``` </details>

andrewrk commented 2026年03月09日 00:18:33 +01:00

Thanks @kristoff, applied your patch. This is ready to land when it passes CI.

Thanks @kristoff, applied your patch. This is ready to land when it passes CI.