Is this no longer needed?
Do callers all make sure the waiting list for that IO is empty before calling fptr_finalize_flush?
And also that no other thread can start a blocking operation between being notified and reaching here?
fd = -1 is only set just above but so after notification, hence it seems possible for other threads to restart their blocking operation (or a new thread to start a blocking operation on this IO), unless we have some flag to prevent that?

I'm probably going to introduce a flag because the fiber scheduler can defer io_close operation using io_uring for better performance, but we can't set fd = -1 to mean "we are closing" because then fd has no meaning after that and can't be used by io_close hook.

This is not ideal, because it means we won't test rb_wait_for_single_fd anymore on Ruby >= 3.
So it'd be better to define a separate function/method and test that separately.

For the other changes above it seems fine because they are all trivial renames or helpers, but it's not that straightforward here.

rb_wait_for_single_fd should be deprecated and removed. How should we handle it?

Is it worth the cost to deprecate it, what's the issue with it?

Every time you call it, the fiber scheduler has to make a temporary IO object, because the design choice was made that it should be IO-instance centric not int fd centric.

I think deprecating this would need feedback from other core devs or matz.
Practically, you'd use one of the DEPRECATED macros, and the specs would stop testing that method when it's removed.

I think it needs to be clear to everyone that both IO#close and struct rb_io is made internal are done by this PR/Redmine ticket (struct rb_io is made internal is not an implementation detail change, it will affect gems).

struct rb_io is made internal is not an implementation detail change, it will affect gems.

Do you know any examples of this?

Usages of RB_IO_POINTER or GetOpenFile seem likely problematic, if they want to access any field of the returned rb_io_t*.
GetOpenFile is used in a bunch of C extension gems.

$ gem-codesearch 'GetOpenFile\b' | wc -l
974

Not all might access fields of it, but I guess many do.

We can add deprecation warnings and alternatives. Most of them are probably just accessing the descriptor.

One problem with such a change is io-console is a gem and supports older Ruby versions, which don't have any rb_ioptr_*.

We can create compatibility macros for this case, wdyt?

Yes, but this needs to be easy then, if rb_ioptr_descriptor is a function then one needs have_func + their own macro, it's annoying already.

Could we keep exposing some fields of struct rb_io public (like fd), and the rest internal? Then there would be much less need to migrate code, which is a significant overhead.

I don't think we should expose any parts of struct rb_io.

Alright.
Maybe we could always define macros like HAVE_RB_IO_DESCRIPTOR which means rb_ioptr_descriptor is available without needing to have_func('rb_ioptr_descriptor') which is quite slow (one C compilation for each function checked).
Or something more direct like RB_IO_DESCRIPTOR(io), and so users can just define it as the old way if not already defined.

I'm not a big fan of the rb_ioptr_ naming. I think rb_io_ is better. That might mean passing the VALUE instead of the struct rb_io, that seems fine and much clearer that structs are not parts of the API (even opaque structs).

I'm okay with this but I'm between a rock and a hard place, I didn't create the interfaces that take the "fptr" argument and I'm all for defining more rb_io_...(VALUE) functions. I agree the less of this we expose the better.