Add memory methods to read into a buffer

[A248]

Plus some simple documentation for Memory itself.

[andreaTP]

Would you mind to elaborate on the need of expanding the public API with those methods?

Happy to hear @andreas-karlsson POV when available

[A248]

Exposing APIs that accept caller-provided buffers is a very common Java practice. In my case, I was implementing an InputStream that reads directly from WASM memory given a pointer + length. Without these APIs, I have to perform arraycopy's on intermediate byte arrays, because the InputStream model relies predominantly on caller-provided buffers.

Buffering a big memory region using ByteArrayInputStream is inefficient, and it is especially wasteful if the whole region is not consumed. Rather than reading chunks as multiple new byte[] objects, it would benefit host-guest memory transfer to utilize the methods introduced by this API, whether for re-usable byte buffers or for APIs like InputStream that need it.

[andreaTP]

Do you mind expanding the current JMH tests to prove the efficiency improvement given by those changes?

[A248]

Why is that a concern?

If the caller has an existing byte[4096], it doesn't make sense to create an intermediate array. This is an extremely common pattern in Java APIs and it seems ridiculous to demand a benchmark. The InputStream API is already designed this way.

[andreaTP]

No specific concerns, additional API increase maintenance, either there is a compelling reason or there is no need to grow the exposed surface.

You are free to implement the Memory interface in your codebase and add anything useful to your project there.

[A248]

Integrating with the Java ecosystem isn't a compelling reason?

This PR has an incredibly small change surface, re-uses default implementations, and is fully documented. I don't want to fork this repository but it seems you are being pedantic.

[andreaTP]

I make an effort to remain professional despite the attitude:

The changes in this PR are usless unless proven, I have done dozens of integrations and never felt the need.

I acknowledge there might be a theoretical minimal benefit, but I'm not up accepting a PR increasing the public API of Memory without proving evidence, being it:

• performance
• a real world need

We have plans for consolidating and shrinking it instead.

Feel free to close the PR and fork if you are not comfortable with the answer.

[A248]

I'm sorry, but I am not the one with an attitude here. You have spoken condescendingly and been intentionally obtuse and hypocritical even as I elaborated patiently.

I am not going to waste time on a benchmark for such an elementary thing and will close this PR.