doc: Document io packages a bit

wader · Nov 21, 2021 · 1047d90 · 1047d90
1 parent 7c4b0b3
commit 1047d90
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 6 deletions.
diff --git a/doc/dev.md b/doc/dev.md
@@ -60,3 +60,25 @@ main:main()
                                         print tree
                                 empty output
 ```
+
+## bitio and other io packages
+
+```
+*os.File, *bytes.Buffer
+^
+ctxreadseeker.Reader defers blocking io operations to a goroutine to make them cancellable
+^
+progressreadseeker.Reader approximates how much of a file has been read
+^
+aheadreadseeker.Reader does readahead caching
+^
+| (io.ReadSeeker interface)
+|
+bitio.Reader (implements bitio.Bit* interfaces)
+^
+| (bitio.Bit* interfaces)
+|
+bitio.Buffer convenience wrapper to read bytes from bit reader, create section readers etc
+SectionBitReader
+MultiBitReader
+```
diff --git a/internal/progressreadseeker/progressreaderseeker.go b/internal/progressreadseeker/progressreaderseeker.go
@@ -6,7 +6,7 @@ import (
 
 type ProgressFn func(approxReadBytes int64, totalSize int64)
 
-type ProgressReaderSeeker struct {
+type Reader struct {
 	rs                  io.ReadSeeker
 	pos                 int64
 	totalSize           int64
@@ -16,12 +16,12 @@ type ProgressReaderSeeker struct {
 	progressFn          ProgressFn
 }
 
-func New(rs io.ReadSeeker, precision int64, totalSize int64, fn ProgressFn) *ProgressReaderSeeker {
+func New(rs io.ReadSeeker, precision int64, totalSize int64, fn ProgressFn) *Reader {
 	partitionSize := totalSize / precision
 	if totalSize%precision != 0 {
 		partitionSize++
 	}
-	return &ProgressReaderSeeker{
+	return &Reader{
 		rs:            rs,
 		totalSize:     totalSize,
 		partitionSize: partitionSize,
@@ -30,7 +30,7 @@ func New(rs io.ReadSeeker, precision int64, totalSize int64, fn ProgressFn) *Pro
 	}
 }
 
-func (prs *ProgressReaderSeeker) Read(p []byte) (n int, err error) {
+func (prs *Reader) Read(p []byte) (n int, err error) {
 	n, err = prs.rs.Read(p)
 	newPos := prs.pos + int64(n)
 	lastPartitionsReadCount := prs.partitionsReadCount
@@ -59,7 +59,7 @@ func (prs *ProgressReaderSeeker) Read(p []byte) (n int, err error) {
 	return n, err
 }
 
-func (prs *ProgressReaderSeeker) Seek(offset int64, whence int) (int64, error) {
+func (prs *Reader) Seek(offset int64, whence int) (int64, error) {
 	pos, err := prs.rs.Seek(offset, whence)
 	prs.pos = pos
 	return pos, err

diff --git a/pkg/interp/bufferrange.go b/pkg/interp/bufferrange.go
@@ -151,7 +151,7 @@ func (i *Interp) _open(c interface{}, a []interface{}) interface{} {
 	const cacheReadAheadSize = 512 * 1024
 	aheadRs := aheadreadseeker.New(fRS, cacheReadAheadSize)
 
-	// bitio.Buffer -> aheadreadseeker -> progressreadseeker -> ctxreadseeker -> readseeker
+	// bitio.Buffer -> (bitio.Reader) -> aheadreadseeker -> progressreadseeker -> ctxreadseeker -> readseeker
 
 	bbf.bb, err = bitio.NewBufferFromReadSeeker(aheadRs)
 	if err != nil {