byteslicereader

Documentation

Overview

Package byteslicereader offers R a slice-backed Reader that offers zero-copy options.

Standard io.Reader methods require that data be copied into a target Buffer. The zero-copy options, Peek and Next, allow for data to be returned as slices of R's underlying Buffer.

With great power comes great responsibility: holding a reference to an underlying Buffer means that the Buffer must persist as long as that reference is valid, and that modifications to that reference must be coordinated with any other consumers.

R allows for APIs that may want to be zero-copy conditionally by exposing an AlwaysCopy flag. If set, R's zero-copy operations will return copies of the underlying Buffer, decoupling them from their base state. Receivers that accept R instances can use it without any modifications.

Index

• type R
  • func (r *R) Next(n int) (v []byte, err error)
  • func (r *R) Peek(n int) []byte
  • func (r *R) PeekByte() (byte, error)
  • func (r *R) Read(b []byte) (amt int, err error)
  • func (r *R) ReadByte() (b byte, err error)
  • func (r *R) Remaining() int
  • func (r *R) Seek(offset int64, whence int) (int64, error)

Types

type R

type R struct {
	// Buffer is the backing buffer for this reader.
	Buffer []byte

	// AlwaysCopy, if true, causes zero-copy methods to return copies of their
	// backing data instead of direct references. This can be set to cause methods
	// that operate on R to automatically own an independent set
	// of data, but obviates the performance benefits.
	//
	// All zero-copy methods honor AlwaysCopy, so it is safe to assume that data
	// returned by all R methods is owned by the caller when
	// AlwaysCopy is true.
	AlwaysCopy bool
	// contains filtered or unexported fields
}

R is an io.Reader-inspired interface that exposes operations that return on byte slices, instead of filling a byte slice.

This allows for efficient zero-copy read operations by returning sections of a backing array.

This is more efficient than copying the data, but carries the peril that, for non-copying calls, the returned data is not independent from the reader's Buffer. Caution must be taken to ensure that references to the underlying Buffer do not persist when/if the buffer is reallocated for other purposes.

Writing to returned Buffer segments is allowed, but caution must be taken not to hand the a section of Buffer to two entities when one of them might write to it.

R can act like an io.Reader and io.ByteReader, allowing it to interface with other APIs at the expense of introducing data copying. This may be acceptable for small amounts of data.

R can be copied, creating a snapshot of its current state.

func (*R) Next

func (r *R) Next(n int) (v []byte, err error)

Next returns the next n bytes in r, advancing r.

Next is a zero-copy equivalent to Read, and returns a slice of the underlying Buffer unless AlwaysCopy is true.

If there are fewer than n bytes in r, Next will return as many bytes as it can and io.EOF as an error. Next will never return an error if all requested bytes are returned.

func (*R) Peek

func (r *R) Peek(n int) []byte

Peek returns the next n bytes in r without advancing it.

Peek is a zero-copy method, and returns a slice of the underlying Buffer unless AlwaysCopy is true.

If there are fewer than n bytes in r, Peek will return as many as possible.

func (*R) PeekByte

func (r *R) PeekByte() (byte, error)

PeekByte is like Peek, but it returns a single byte.

func (*R) Read

func (r *R) Read(b []byte) (amt int, err error)

Read implements io.Reader.

Note that using Read cause data to be copied.

func (*R) ReadByte

func (r *R) ReadByte() (b byte, err error)

ReadByte implements io.ByteReader.

func (*R) Remaining

func (r *R) Remaining() int

Remaining returns the number of bytes remaining in the reader, from the current position.

func (*R) Seek

func (r *R) Seek(offset int64, whence int) (int64, error)

Seek implements io.Seeker.