From 21088f2cb5965119897433279957e2ad2b301ddd Mon Sep 17 00:00:00 2001 From: Jack Christensen Date: Sat, 8 Jun 2019 18:29:13 -0500 Subject: [PATCH] Improve documentation --- README.md | 2 +- chunkreader.go | 14 ++++++++++---- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bcc9ac6b..01209bfa 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,6 @@ # chunkreader -Package chunkreader provides an opinionated, efficient buffered reader. +Package chunkreader provides an io.Reader wrapper that minimizes IO reads and memory allocations. Extracted from original implementation in https://github.com/jackc/pgx. diff --git a/chunkreader.go b/chunkreader.go index b47747f2..36304fd5 100644 --- a/chunkreader.go +++ b/chunkreader.go @@ -1,11 +1,17 @@ -// Package chunkreader provides an opinionated, efficient buffered reader. +// Package chunkreader provides an io.Reader wrapper that minimizes IO reads and memory allocations. package chunkreader import ( "io" ) -// ChunkReader is a io.Reader wrapper that minimizes reads and memory allocations. +// ChunkReader is a io.Reader wrapper that minimizes IO reads and memory allocations. It allocates memory in chunks and +// will read as much as will fit in the current buffer in a single call regardless of how large a read is actually +// requested. The memory returned via Next is owned by the caller. This avoids the need for an additional copy. +// +// The downside of this approach is that a large buffer can be pinned in memory even if only a small slice is +// referenced. For example, an entire 4096 byte block could be pinned in memory by even a 1 byte slice. In these rare +// cases it would be advantageous to copy the bytes to another slice. type ChunkReader struct { r io.Reader @@ -43,8 +49,8 @@ func NewConfig(r io.Reader, config Config) (*ChunkReader, error) { }, nil } -// Next returns buf filled with the next n bytes. If an error occurs, buf will -// be nil. +// Next returns buf filled with the next n bytes. The caller gains ownership of buf. It is not necessary to make a copy +// of buf. If an error occurs, buf will be nil. func (r *ChunkReader) Next(n int) (buf []byte, err error) { // n bytes already in buf if (r.wp - r.rp) >= n {