Document that write_buffer_with is sound to read from.

[kpreid]

Checklist

• Run cargo clippy.
• Run RUSTFLAGS=--cfg=web_sys_unstable_apis cargo clippy --target wasm32-unknown-unknown if applicable.
• Add change to CHANGELOG.md. See simple instructions inside file.

Description

To a reader informed about Rust's memory model, the existing claim that

dereferencing it to a &[u8] panics

without further context sounds awfully like someone thinks they've invented a write-only reference, and that the API might actually be exposing undefined behavior via an uninitialized &mut [u8]. Therefore, let's specify what happens if you do read through the mutable reference. The text added in this commit is based on what was said in the review when write_buffer_with was added.

This is also relevant information to someone considering using write_buffer_with() for performance gains: for example, it suggests that it might be a bad idea to write data into the view and then sort it in-place. (Or is that not a bad idea? Is it not slow if the CPU already wrote over all the memory contiguously? I don't know.)

[cwfitzgerald]

Thanks!

[cwfitzgerald]

As for:

it suggests that it might be a bad idea to write data into the view and then sort it in-place

Currently it will be fast, but we reserve the right (and we might do it) to make it terribly slow

[kpreid]

Currently it will be fast, but we reserve the right (and we might do it) to make it terribly slow

Another question that comes to mind is whether this also applies to buffers created as mapped_at_creation. If so, that is worth documenting too. In my own thinking about perf optimization, I've thought about doing (as I mentioned in the description) sorting or other read-write operations inside of newly allocated buffers or StagingBelt views, on the principle of minimizing copies.