Misc #22506: Clarify read-only, lock and freeze in IO::Buffer

• Status: Open
• Assignee: -

[himura467 (Akito Shitara)]

Following https://bugs.ruby-lang.org/issues/22274#note-16, I'd like to agree on what each of these means for IO::Buffer, so that the remaining fixes follow one model. This is a proposal, and I'd appreciate corrections.

	What it prevents	Duration
read-only	writes through this buffer	set at creation
lock	freeing, resizing or transferring the memory	while a native operation borrows it
freeze	any change made through this buffer, including writes to its bytes	permanent

None of them promises that the bytes cannot change through another view or another process.

Proposed rules:

• A frozen buffer refuses writes (FrozenError), and a read-only one refuses writes (AccessError), like a frozen File and a File opened with "r".
• readonly? and the READONLY flag from rb_io_buffer_get_bytes report whether the memory may be written through this buffer, not whether the buffer is frozen. A frozen source makes its slices read-only, but freezing a buffer does not make the buffer itself read-only, so C code should write through rb_io_buffer_get_bytes_for_writing, which checks both.
• A frozen buffer cannot be freed, resized or transferred, so locking it is unnecessary and can be a no-op.
• A locked buffer cannot be frozen (https://bugs.ruby-lang.org/issues/22274#note-10), like a temporarily locked String.

Open questions:

1. The owner of borrowed memory (a buffer from rb_io_buffer_new without a source) has to invalidate the buffer before reclaiming the memory, even if the code it was lent to has frozen or locked it. Should invalidation by the owner be an exception to the rules above, or should such a buffer refuse to be frozen?
2. With this model, a frozen buffer is no longer writable. If a buffer that stays writable while its memory is guaranteed to stay accessible is needed beyond what holding a lock provides, I wouldn't object to expressing that state with a separate name such as #pin (https://bugs.ruby-lang.org/issues/22274#note-18). @ioquatix (Samuel Williams), is there a reason or use case for expressing it with freeze instead?

[Eregon (Benoit Daloze)]

+1, I think this is the intuitive and consistent semantics with the rest of Ruby.

himura467 (Akito Shitara) wrote:

A frozen buffer cannot be freed, resized or transferred, so locking it is unnecessary and can be a no-op.

A frozen buffer might still be moved (by the GC) though, which needs to be prevented during native calls (e.g. write(2)).
That might already work though through the fact that VALUEs on the stack are pinned while on the stack.