Add Flow.read_all

[SGrondin]

This is really basic, but it's something that I've found useful to have.

When I first started experimenting with Eio, the only slight pain point I encountered at the very beginning was trying to understand how Flows, Files, Fs, Flow.Buf_read, etc, worked together. Having this simple function would have helped me understand it all.

It can also be useful for debugging.

[rbjorklin]

Would it make sense to have the buffer size be configurable through an optional parameter? ?(size = 4096)?

[SGrondin]

Possibly. I debated whether to do it or not. Ultimately I went with no because Buffer_sink.copy just 20 lines above also doesn't. Plus I figured that any situation where the buffer size would have an impact would not use a function that loads everything into a single large string; it would process the file in small chunks instead. It made sense to me to keep this "beginner function" as simple as possible.

[talex5]

Having a function like this might be good. Going via Buffer probably isn't a good idea (because then we read into a cstruct, copy it into the buffer, then copy it out again for the final string).

It can be done at the moment with e.g.

let read_all flow =
  Eio.Buf_read.(parse_exn take_all) flow ~max_size:max_int

Having this in Flow might be more discoverable, but requires a little bit of extra work to avoid a cyclic dependency (because Buf_read depends on Flow).

[SGrondin]

I used Buffer to avoid the dependency issue since this function isn't meant to be ultra performant. I'll give it another shot this weekend and see what I can do.

[SGrondin]

@talex5 I rewrote it using Buf_read. I tried a few different approaches to break the cyclic dependency and I think this is the simplest way. If a better way exists, feel free to close this PR.

Edit: I'm not convinced the performance is worth the extra complexity if this function is not intended as more than a debugging or discovery or small scale tool.

[talex5]

I tried a few different approaches to break the cyclic dependency and I think this is the simplest way. If a better way exists, feel free to close this PR

A simpler way might be to add it in eio.ml, e.g.

module Buf_read = Buf_read
module Flow = struct
  include Flow
  let read_all = ...
end

[SGrondin]

Great idea, I like that a lot better.

EDIT: done. Much better 🎉

[talex5]

Looks good - I just made some minor changes to the doc-strings.