feat: dynamic stream buffer

[francisdb]

This pull request introduces a new dynamically growing buffer implementation for streams, replacing the previous fixed-size buffer approach.

This introduces a breaking change as the options on the Stream have been moved to the CompundFile. Also you now configuring max_buffer_size instead of buffer_size with a default of 1 MiB.

I ran the original benchmark and with buffer size ignored there were only improvements, no regressions. So I removed the specific benchmarks per buffer size.

[francisdb]

@mdsteele that max_buffer_size would probably make more sense to be configured for the whole cfb file instead of per stream. This for memory-constrained environments. What are your thoughts?

[mdsteele]

Thanks for working on this!

If this is a better/more-performant design, then I think a breaking change here makes sense; the API that would get broken was only just recently published, so probably not a lot of dependencies on it yet, and anyway this is a pre-1.0 crate.

Making this a per-CompoundFile setting seems reasonable to me too. In that case, my initial gut is we should:

1. Just remove CreateStreamOptions and OpenStreamOptions (and their associated methods) entirely
2. Add a new OpenOptions for CompoundFile, with max_buffer_size and strict settings, leaving CompoundFile::open and CompoundFile::open_strict as convenience methods
3. Ideally, make cfb::OpenOptions be as similar as possible to std::fs::OpenOptions, which I guess would mean putting the open() method on cfb::OpenOptions rather than adding a CompoundFile::open_with_options method? Although maybe we'd want two methods, one that takes an F and a convenience one that takes an AsRef<Path>, not sure.

But I'm totally open to something else if you suggest otherwise.

[francisdb]

@mdsteele want me to split up to OpenOptions and CreateOptions or do you think it's ok to do open_options.create() and having the strict being ignored?

[francisdb]

Looks like this caused a regression on the read side. Adding a read benchmark.

[francisdb]

All done. Question on the single or split options remains.

[mdsteele]

@mdsteele want me to split up to OpenOptions and CreateOptions or do you think it's ok to do open_options.create() and having the strict being ignored?

Oh, hmm. I think effectively ignoring the strict setting on create() is probably fine; the crate always tries to be strict when creating files anyway. Maybe there could be other options we'd add in the future that would only make sense for one or the other? I guess if necessary we could just make it an error to call, say, open() when using an option that really only makes sense for create().

[francisdb]

Want me to squash everything?

[mdsteele]

Looks great, thanks

[francisdb]

@mdsteele mind releasing this?
I'm switching to other projects for now. Further optimizations will be for later. (tree balancing, tree node name caching, iteration improvements).

[mdsteele]

Sounds good, thanks. Published as v0.14.0.