Document IO::Buffer

[zverok]

The "demo" of the new docs: https://zverok.github.io/ruby-rdoc/IO/Buffer.html

The docs are written on "to the best of my understanding" basis 🤷
(For example, I am not sure why #tranfer might be useful?)

See also accompanying "inconsistencies and problems discovered" ticket: https://bugs.ruby-lang.org/issues/18417

[zverok]

@ioquatix Please review

[ioquatix]

Thanks to @rawrafox who proposed we implement #transfer semantics based on some of the existing designs from JS: https://github.com/tc39/proposal-resizablearraybuffer and https://github.com/domenic/proposal-arraybuffer-transfer/blob/d4e00037420b87d0b5662c82b74d56b4ba1562ad/README.md (has a really good explanation of the problem).

In IO::Buffer we are solving this in two ways, one is to use locking with a flag, and one is to use #transfer (move semantics). All of this is subject to change but I think it's a good time for us to experiment.

[ioquatix]

I am going to give a thorough review of this today. A quick check, this looks amazing.

[eregon]

That doesn't sound right semantically, it sounds more like a bug.
Also this could easily corrupt memory/make things crash/segfault if e.g. a fstring is passed and it's mutated by IO::Buffer.

[ioquatix]

Yes you are right it was a bug, we have fixed it already. The buffer created from frozen string will be immutable.

[zverok]

we implement #transfer semantics based on some of the existing designs from JS

Oh, now I get it. Would something like that make sense as a docs for the method?

Transfers ownership to a new buffer, deallocating the current one. This method is useful for implementing the move semantics for safe buffer processing, especially in multi-threaded environments.

simple example from the docs here

How it will help to implement working with buffer safely:

buffer = fill_the_buffer

Thread.new { some_complicated_writing_operation(buffer) }

# ... if here, some code accidentally changes a buffer, it _might_ happen before the writing will be done
# ...instead, we can "move" (transfer) buffer to a writer to underline it shouldn't be used anymore

Thread.new { some_complicated_writing_operation(buffer.transfer) }

buffer.copy('foo', 0) # will raise

[rawrafox]

I think something like Creates a new buffer with the same content as this one, frees itself, and then returns the new buffer might be a little clearer since it explains what is transferred and that the method it effectively calls afterwards is IO::Buffer#free.

[ioquatix]

I'm going to merge this by hand (trying to get this done as much as possible before rc1 deadline).

[ioquatix]

I don't know if we ever included the final update regarding #transfer if anyone has a moment to check it looks good based on the discussion it would be most appreciated.