binary/stream/reader: Fast-path offsetReader skips

[abhinav]

Before streaming, when we were working off an in-memory buffer, skipping
bytes was very cheap: offset += n. The streaming implementation relies
on io.CopyN(ioutil.Discard) to skip bytes.

This is comparatively inefficient because:

1. We have to copy bytes for them to be discarded
2. io.CopyN makes a new buffer for each call

This change addresses (1) for the common case of using the non-streaming
reader: if the io.Reader that we're streaming from is an
offsetReader, we optimize our skips by simply incrementing its offset.

Naively, we might do this by adding two implementations of discard on
StreamReader and picking between them at initialization.

type StreamReader struct {
    // ...
    discard func(int64) error
}

func NewStreamReader(r io.Reader) *StreamReader {
    sr := StreamReader{...}
    if condition {
        sr.discard = sr.discardStream
    } else {
        sr.discard = sr.discardOffset
    }
    // ...
}

Except that alone isn't enough. The sr.discard = sr.discardStream
assignment causes an allocation because we're referencing a bound method
of an instance of the object. It's roughly equivalent to allocating a
closure:

sr.discard = func(n int64) error { return sr.discardStream(n) }

To do this more efficiently, we'll hold onto the pointers to the bound
methods discardStream and discardOffset on the pooled StreamReader
object. This is the same technique employed in binary.Writer to avoid
similar allocations for writeValue and writeMapItem.

name                                                  old time/op    new time/op    delta
RoundTrip/PrimitiveOptionalStruct/Decode-4              2.91µs ± 6%    2.90µs ± 1%     ~     (p=0.497 n=10+9)
RoundTrip/PrimitiveOptionalStruct/Streaming_Decode-4    1.85µs ± 4%    1.84µs ± 2%     ~     (p=0.691 n=9+8)
RoundTrip/Graph/Decode-4                                9.64µs ± 1%    6.36µs ± 2%  -34.02%  (p=0.000 n=10+9)
RoundTrip/Graph/Streaming_Decode-4                      2.69µs ± 4%    2.69µs ± 4%     ~     (p=0.495 n=8+9)
RoundTrip/ContainersOfContainers/Decode-4               79.1µs ±27%    56.6µs ± 1%  -28.50%  (p=0.000 n=10+10)
RoundTrip/ContainersOfContainers/Streaming_Decode-4     30.3µs ± 2%    30.5µs ± 5%     ~     (p=0.696 n=8+10)

name                                                  old alloc/op   new alloc/op   delta
RoundTrip/PrimitiveOptionalStruct/Decode-4              1.40kB ± 0%    1.40kB ± 0%     ~     (all equal)
RoundTrip/PrimitiveOptionalStruct/Streaming_Decode-4     56.0B ± 0%     56.0B ± 0%     ~     (all equal)
RoundTrip/Graph/Decode-4                                3.52kB ± 0%    2.80kB ± 0%  -20.54%  (p=0.000 n=7+10)
RoundTrip/Graph/Streaming_Decode-4                        168B ± 0%      168B ± 0%     ~     (all equal)
RoundTrip/ContainersOfContainers/Decode-4               15.7kB ± 0%    13.2kB ± 0%  -16.28%  (p=0.000 n=10+8)
RoundTrip/ContainersOfContainers/Streaming_Decode-4     10.1kB ± 0%    10.1kB ± 0%     ~     (p=0.059 n=8+10)

name                                                  old allocs/op  new allocs/op  delta
RoundTrip/PrimitiveOptionalStruct/Decode-4                14.0 ± 0%      14.0 ± 0%     ~     (all equal)
RoundTrip/PrimitiveOptionalStruct/Streaming_Decode-4      10.0 ± 0%      10.0 ± 0%     ~     (all equal)
RoundTrip/Graph/Decode-4                                  63.0 ± 0%      33.0 ± 0%  -47.62%  (p=0.000 n=10+10)
RoundTrip/Graph/Streaming_Decode-4                        10.0 ± 0%      10.0 ± 0%     ~     (all equal)
RoundTrip/ContainersOfContainers/Decode-4                  306 ± 0%       200 ± 0%  -34.64%  (p=0.000 n=10+9)
RoundTrip/ContainersOfContainers/Streaming_Decode-4        146 ± 0%       146 ± 0%     ~     (p=1.000 n=10+10)

[codecov]

Codecov Report

Merging #519 (933dc23) into streamdev (ce4445d) will decrease coverage by 0.00%.
The diff coverage is 100.00%.

@@              Coverage Diff              @@
##           streamdev     #519      +/-   ##
=============================================
- Coverage      68.83%   68.83%   -0.01%     
=============================================
  Files            130      130              
  Lines          22755    22767      +12     
=============================================
+ Hits           15663    15671       +8     
- Misses          4069     4071       +2     
- Partials        3023     3025       +2     

Impacted Files	Coverage Δ
protocol/binary/stream_reader.go	100.00% <100.00%> (ø)
protocol/binary/reader.go	82.14% <0.00%> (-3.58%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ce4445d...933dc23. Read the comment docs.