rangeio

type Config struct {
	// MaxParallelism is the maximum number of goroutines that may be used to
	// read ranges in parallel. If MaxParallelism <= 0, [runtime.NumCPU] is
	// used.
	//
	// Ranges are split into smaller ranges (no smaller than MinRangeSize) to
	// get as close as possible to MaxParallelism.
	//
	// If MaxParallelism is 1, ReadRanges will read each range sequentially.
	MaxParallelism int `yaml:"max_parallelism" category:"experimental"`

	// CoalesceSize determines the maximum size (in bytes) of a gap between each
	// pair of ranges that causes them to be coalesced into a single range.
	CoalesceSize int `yaml:"coalesce_size" category:"experimental"`

	// MaxRangeSize determines the maximum size (in bytes) of a range. Ranges
	// won't be coalesced if they exceed this size, and existing ranges will be
	// split if they exceed this size (down to MinRangeSize).
	MaxRangeSize int `yaml:"max_range_size" category:"experimental"`

	// MinRangeSize determines the minimum size (in bytes) of a range. When a
	// range is split, it won't be split into units smaller than MinRangeSize.
	MinRangeSize int `yaml:"min_range_size" category:"experimental"`
}

type Range struct {
	// Data to read into; exactly len(Data) bytes will be read, or an error will
	// be returned.
	Data []byte

	// Offset to start reading from.
	Offset int64
}

type Reader interface {
	// ReadRange reads len(r.Data) bytes into r.Data starting at r.Offset in the
	// underlying input source.
	//
	// It returns the number of bytes read (0 <= n <= len(r.Data)) and any error
	// encountered.
	//
	// When ReadRange returns n < len(r.Data), it returns a non-nil error
	// explaining why more bytes were not returned. The error must be [io.EOF]
	// when reading beyond the end of the input source.
	//
	// ReadRange may use all of r.Data as scratch space during the call, even if
	// less than len(r.Data) bytes are read. If some data is available but not
	// len(r.Data) bytes, ReadRange blocks until either all the data is
	// available or an error occurs.
	//
	// Implementations are recommended but not required to immediately respond
	// to the cancellation of ctx; for example, cancellation may not occur
	// immediately when using disk-based I/O.
	//
	// If the len(r.Data) bytes returned by ReadRange are at the end of the
	// input source, ReadRange may return either err == [io.EOF] or err == nil.
	//
	// If ReadRange is reading from an input source with a seek offset,
	// ReadRange should not affect nor be affected by the underlying seek
	// offset.
	//
	// It is safe to call ReadRange concurrently from multiple goroutines.
	//
	// Implementations must not retain r.Data after the call returns.
	ReadRange(ctx context.Context, r Range) (int, error)
}