ioqueue

type Buffer interface {
	// Len reports the size of the buffer,
	// which is the number of written, but unread bytes.
	// It is equivalent to atomically subtracting
	// the ReadOffset from the WriteOffset.
	Len() int64

	// WriteOffset is the total number of bytes written.
	// It is an increasing monotonic counter
	// and is always greater than or equal to ReadOffset.
	WriteOffset() int64

	// ReadOffset is the total number of bytes read.
	// It is an increasing monotonic counter
	// and is always less than or equal to WriteOffset.
	ReadOffset() int64

	// Write writes data to the end of the buffer,
	// atomically incrementing Len and WriteOffset
	// by the amount of bytes written.
	// Concurrent Write calls are atomically performed.
	// Write does not block.
	Write([]byte) (int, error)

	// Read reads data from the front of the buffer, atomically decrementing
	// Len and incrementing ReadOffset by the amount of bytes read.
	// It never reads partially written data for a concurrent Write call.
	// It fills the buffer with as much data as is available.
	// Rather than blocking, it returns ErrEmpty when the buffer is empty.
	// Use WaitUntil to block until data is available.
	//
	// A concrete implementation that supports closing the write side
	// may return io.EOF once the buffer is closed for writing
	// and no further bytes will ever be produced
	// (after any remaining data has been read).
	// ErrEmpty must not be used for that permanent condition.
	Read([]byte) (int, error)

	// Peek copies data from the front of the buffer into b
	// without affecting Len or ReadOffset.
	// It never peeks partially written data for a concurrent Write call.
	// It fills the buffer with as much data as is available.
	// If len(b) is greater than Len, then it only copies the available content.
	// It reports the current ReadOffset and the number of bytes copied into b.
	// If the number of available bytes is zero, it reports ErrEmpty.
	//
	// A concrete implementation that supports closing the write side
	// may return io.EOF once the buffer is closed for writing
	// and no further bytes will ever be produced
	// (when no buffered data remains).
	//
	// The content peeked can be later discarded as follows:
	//
	//	readOffset, n, err := buf.Peek(b)
	//	... // make use of b[:n]
	//	_, err := buf.DiscardUntil(readOffset + n)
	Peek(b []byte) (readOffset int64, n int64, err error)

	// DiscardUntil discards bytes from the front of the buffer by
	// incrementing ReadOffset to match the specified readOffset.
	// If readOffset is less than ReadOffset,
	// then ReadOffset is not changed and no error is reported.
	// If readOffset is greater than WriteOffset, then ReadOffset is
	// set to the current WriteOffset and reports [ErrEmpty]
	// (or [io.EOF] if the implementation supports closing the write side).
	// It reports the number of bytes that have been discarded.
	// If readOffset is less than or equal to WriteOffset,
	// it should never report [ErrEmpty] or [io.EOF].
	DiscardUntil(readOffset int64) (n int64, err error)

	// WaitUntil returns a channel that is closed
	// when the WriteOffset exceeds the specified writeOffset.
	//
	// To wait for the buffer to have more than n bytes:
	//
	//	<-b.WaitUntil(b.ReadOffset() + n)
	//
	// This method is useful for blocking until the buffer contains
	// more than n bytes to enforce limits on maximum buffer size
	// or to upload in larger batches for greater efficiency.
	//
	// If a concrete implementation supports closing the write side,
	// it should close outstanding and future WaitUntil channels as needed
	// so waiters do not block indefinitely after close.
	WaitUntil(writeOffset int64) <-chan struct{}
}

type VolatileBuffer struct {
	// contains filtered or unexported fields
}