Document Fiber::SchedulerInterface#io_read and #io_write

[zverok]

Screenshot (ignore #io_wait):

[zverok]

@ioquatix Please review. Should other details be mentioned? Is the description correct overall?

[ioquatix]

This looks good.

io_read

The length argument is the "minimum length to be read".

If the IO buffer is big, e.g. 8KiB, but the length is 1KiB, up to 8KiB might be read, but at least 1KiB will be.

io_write

The length argument is the "[maximum] length to be written".

If the IO buffer is big, e.g. 8KiB, but the length is 1KiB, at most 1KiB will be written. Generally, the only case where less data can be written is if there is an error writing the data.

[ioquatix]

Please mark/tag io_write and io_read as experimental.

[ioquatix]

I had to make some internal changes to the hooks, I will have some updates to this documentation in a day or two.

#5287

[zverok]

@ioquatix Is that what you had in mind? I am not sure—maybe I am lost a bit—whether the new interface is expected to return "length or -errno" (how I described it) or [-errno, length] (hmm, that's what your PR's title says?..)

[ioquatix]

Yes, this interface can return an integer in the range of [-errno, length].

I provided C interface to hide exact implementation details of the VALUE returned: https://github.com/ruby/ruby/pull/5287/files#diff-1552659974ee1047f418def875393a583c6a8c543e446755a52acdcae5467fc1R28-R47

FYI Linux internally follows this model and libc writes the return value to errno: https://yarchive.net/comp/linux/errno.html from Linus himself.

[ioquatix]

@zverok thanks so much for helping with this.

[bryanp]

👍 This is great.

[zverok]

@ioquatix I've applied your suggestions, thanks! 🤗
I also added two more methods docs (wanted to do in a separate PR, but it actually makes more sense to handle it all once and for good):

#address_resolve

#timeout_after

[ioquatix]

I wonder if it would make sense to move this pseudo-implementation to scheduler.c just to avoid making cont.c more burdened.

[ioquatix]

@zverok I've asked the author of address_resolve hook @bruno- to provide/update the documentation.