Split socket/SSLSocket nonblock methods into `exception:` overloads by zonuexe · Pull Request #2963 · ruby/rbs

zonuexe · 2026-05-21T06:38:16Z

Summary

The non-blocking socket methods (and OpenSSL SSLSocket equivalents) take an exception: keyword that selects the return value: the normal result when exception: true (the default), or a :wait_readable / :wait_writable symbol when exception: false. The signatures expressed this with a single ?exception: boolish parameter and a union return type (or plain untyped), so the symbol leaked into the result type even when exception: was not passed.

This splits each method into true / false literal overloads so the return type reflects the argument — the same treatment applied to StringScanner#scan_full / #search_full in #2959.

Ruby Method	Change	C function
`BasicSocket#recv_nonblock`	Split `exception:` into `true`/`false` overloads (`false` → `… \| :wait_readable`)	`rsock_s_recvfrom_nonblock`
`BasicSocket#recvmsg_nonblock`	Split `exception:` into `true`/`false` overloads (`false` → `… \| :wait_readable`)	`rsock_bsock_recvmsg_nonblock`
`BasicSocket#sendmsg_nonblock`	Split `exception:` into `true`/`false` overloads (`false` → `… \| :wait_writable`)	`rsock_bsock_sendmsg_nonblock`
`OpenSSL::SSL::SSLSocket#sysread_nonblock`	Replace `(*untyped) -> untyped` with `true`/`false` overloads (`false` → `… \| :wait_readable \| :wait_writable \| nil`)	`ossl_ssl_read_nonblock`
`OpenSSL::SSL::SSLSocket#syswrite_nonblock`	Replace `(*untyped) -> untyped` with `true`/`false` overloads (`false` → `… \| :wait_readable \| :wait_writable \| nil`)	`ossl_ssl_write_nonblock`
`Socket#accept_nonblock`	Split `exception:` into `true`/`false` overloads (`false` → `… \| :wait_readable`)	`rsock_s_accept_nonblock`
`Socket#connect_nonblock`	Split `exception:` into `true`/`false` overloads (`false` → `… \| :wait_writable`)	`sock_connect_nonblock`
`Socket#recvfrom_nonblock`	Split `exception:` into `true`/`false` overloads (`false` → `… \| :wait_readable`)	`rsock_s_recvfrom_nonblock`
`TCPServer#accept_nonblock`	Split `exception:` into `true`/`false` overloads (`false` → `… \| :wait_readable`)	`rsock_s_accept_nonblock`
`UDPSocket#recvfrom_nonblock`	Split `exception:` into `true`/`false` overloads (`false` → `… \| :wait_readable`)	`rsock_s_recvfrom_nonblock`
`UNIXServer#accept_nonblock`	Split `exception:` into `true`/`false` overloads (`false` → `… \| :wait_readable`)	`rsock_s_accept_nonblock`

Out of scope

The OpenSSL read_nonblock, write_nonblock, connect_nonblock, and accept_nonblock methods already use true/false overloads — no change needed.
read_nonblock / write_nonblock are not redefined under stdlib/socket; they inherit the core IO signatures, which already have the overloads.
PTY.check(pid, raise) is a related parameter-driven return type (raise: true can only return nil), but it belongs to a different method family rather than non-blocking I/O; left for a separate change.

Test plan

bundle exec rbs -r socket validate
bundle exec rbs -r openssl validate
bundle exec rubocop stdlib/socket/0/ stdlib/openssl/0/openssl.rbs

The `exception:` keyword of the non-blocking socket methods selects the return value: the normal result when `exception: true` (the default), or a `:wait_readable` / `:wait_writable` symbol when `exception: false`. Express this with `true`/`false` literal overloads instead of a single `?exception: boolish` parameter with a union return type.

…erloads `SSLSocket#sysread_nonblock` and `#syswrite_nonblock` were typed as `(*untyped) -> untyped`. Like the other non-blocking methods, their `exception:` keyword selects the return value: the normal result when `exception: true` (the default), or a `:wait_readable` / `:wait_writable` symbol (or `nil`) when `exception: false`. Express this with `true`/`false` literal overloads.

ksss · 2026-05-22T06:17:20Z

+      def syswrite_nonblock: (_ToS string, ?exception: true) -> Integer
+                           | (_ToS string, exception: false) -> (Integer | :wait_readable | :wait_writable | nil)


The _ToS interface applies to all objects except BasicObject (e.g., nil, Hash, etc.). However, the actual implementation uses StringValue, and objects like nil should be excluded. I think string is appropriate.

And, Based on the implementation, syswrite_nonblock raises an error even when exception: false is specified. This is asymmetric to sysread_nonblock.
It seems there is no possibility of it returning nil.

ksss · 2026-05-22T06:19:28Z

  #
-  def recv_nonblock: (Integer maxlen, ?Integer flags, ?String buf, ?exception: boolish) -> (String | :wait_readable)
+  def recv_nonblock: (Integer maxlen, ?Integer flags, ?String buf, ?exception: true) -> String
+                   | (Integer maxlen, ?Integer flags, ?String buf, exception: false) -> (String | :wait_readable)


Since the documentation states that Socket#recv_nonblock returns nil, there is a possibility that nil may be returned; the same may be true for recvmsg_nonblock and Socket#recvfrom_nonblock.

Per review feedback: - `SSLSocket#syswrite_nonblock`: - Use `string` (= `String | _ToStr`) instead of `_ToS` for the argument: the C implementation uses `StringValue`, which converts via `to_str`, so `nil`, `Hash`, etc. are not accepted. - Remove `nil` from the `exception: false` return: unlike `sysread_nonblock`, write has no EOF-equivalent path that returns `nil`; it raises on real errors and only converts wait-state into `:wait_readable` / `:wait_writable`. - `BasicSocket#recv_nonblock`, `BasicSocket#recvmsg_nonblock`, `Socket#recvfrom_nonblock`, `UDPSocket#recvfrom_nonblock`: include `nil` in both `exception: true` and `exception: false` overloads. The rdoc states that these methods return `nil` when the underlying `recvfrom(2)` returns 0 (closed connection or empty datagram), regardless of `exception:`.

soutaro · 2026-05-30T14:20:54Z

  # *   Socket#recvfrom
  #
-  def recvfrom_nonblock: (Integer maxlen, ?Integer flags, ?untyped outbuf, ?exception: boolish) -> ([ String, Addrinfo ] | :wait_readable)
+  def recvfrom_nonblock: (Integer maxlen, ?Integer flags, ?untyped outbuf, ?exception: true) -> [ String, Addrinfo ]?


Claude Code told me that nil won't return from this method. Is it correct?

soutaro · 2026-05-30T14:25:43Z

      #
-      def sysread_nonblock: (*untyped) -> untyped
+      def sysread_nonblock: (Integer length, ?String buffer, ?exception: true) -> String
+                          | (Integer length, ?String buffer, exception: false) -> (String | :wait_readable | :wait_writable | nil)


Suggested change

| (Integer length, ?String buffer, exception: false) -> (String | :wait_readable | :wait_writable | nil)

| (Integer length, ?String buffer, exception: boolish) -> (String | :wait_readable | :wait_writable | nil)

exception: keyword parameter must be wider than false, because the precise type information may be lost: exception = rand() > 0.5 #: bool.

I found exception: accepts any object (..., exception: "true"), but it's really complicated to support these cases. So, the assumption, programmers will write the exception: true, would make sense.

zonuexe added 2 commits May 21, 2026 15:37

zonuexe changed the title ~~Split socket nonblock methods into exception: overloads~~ Split socket/SSLSocket nonblock methods into exception: overloads May 21, 2026

zonuexe mentioned this pull request May 21, 2026

Split parameter-driven return types into overloads #2965

Open

4 tasks

ksss reviewed May 22, 2026

View reviewed changes

ksss added this to the RBS 4.1 milestone May 28, 2026

soutaro reviewed May 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Split socket/SSLSocket nonblock methods into `exception:` overloads#2963

Split socket/SSLSocket nonblock methods into `exception:` overloads#2963
zonuexe wants to merge 3 commits into
ruby:masterfrom
zonuexe:fix/nonblock-exception-overloads

zonuexe commented May 21, 2026 •

edited

Loading

Uh oh!

ksss May 22, 2026

Uh oh!

ksss May 22, 2026

Uh oh!

soutaro May 30, 2026

Uh oh!

soutaro May 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		def syswrite_nonblock: (_ToS string, ?exception: true) -> Integer
		\| (_ToS string, exception: false) -> (Integer \| :wait_readable \| :wait_writable \| nil)

	\| (Integer length, ?String buffer, exception: false) -> (String \| :wait_readable \| :wait_writable \| nil)
	\| (Integer length, ?String buffer, exception: boolish) -> (String \| :wait_readable \| :wait_writable \| nil)

Conversation

zonuexe commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Out of scope

Test plan

Uh oh!

ksss May 22, 2026

Choose a reason for hiding this comment

Uh oh!

ksss May 22, 2026

Choose a reason for hiding this comment

Uh oh!

soutaro May 30, 2026

Choose a reason for hiding this comment

Uh oh!

soutaro May 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zonuexe commented May 21, 2026 •

edited

Loading