Pool file handles used by StreamBinaryReader components

[56quarters]

What this PR does

Add a pool of file handles to avoid the cost of opening and closing files for each operation that needs access to the index-header file (symbols and posting offsets). The default number of handles to keep per index-header is 1 to maintain parity with the existing mmap implementation (which keeps a single file handle for the index-header open for the duration of the reader).

Which issue(s) this PR fixes or relates to

See #3465

Benchmark

$ benchstat -delta-test=none old.txt new.txt 
name                                   old time/op    new time/op    delta
DecbufFactory_NewDecbufAtUnchecked-16    2.98µs ± 0%    0.86µs ± 0%  -71.12%

name                                   old alloc/op   new alloc/op   delta
DecbufFactory_NewDecbufAtUnchecked-16      232B ± 0%       48B ± 0%  -79.31%

name                                   old allocs/op  new allocs/op  delta
DecbufFactory_NewDecbufAtUnchecked-16      4.00 ± 0%      1.00 ± 0%  -75.00%

Checklist

• Tests updated
• Documentation added
• CHANGELOG.md updated - the order of entries should be [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX]

[osg-grafana]

Unblocking with feedback

[charleskorn]

Looks good to me. It might be good to add some tests to exercise the pooling behaviour, for example:

• create a second Decbuf while holding the first open
• retrieve a new Decbuf from the factory after closing one (and therefore returning the file handle to the pool) and check that the file handle is reset correctly etc.

[colega]

LGTM, thanks!

[pracucci]

Great job! I did a relatively quick review, but I couldn't spot any issue. I just left few minor comments.

[56quarters]

I ended up implementing the change described here because the logic for cleanup was getting a little confusing being split between the FileReader, Decbuf, and DecbufFactory. Now callers just call Decbuf.Close() (io.Closer) and anything that was pooled is put back into whatever pool it came from.

[charleskorn]

Three very minor nits but otherwise LGTM.