README
¶
Buffer
Pooled Buffer IO for Go programs.
Package buffer provides a reader implementation similar to bufio.Reader. The underlying memory buffers can be used from a synchronized pool. It also supports scenarios similar to io.Pipe, where a content writer process is wrapped by a buffered reader.
Find the documentation here:
Made in Berlin, DE
Documentation
¶
Overview ¶
Package buffer provides pooled Buffer IO for Go programs.
It implements a reader similar to bufio.Reader. The underlying memory buffers can be used from a synchronized pool.
Index ¶
- Variables
- type ContentFunc
- type Options
- type Pool
- type Reader
- func (r Reader) Buffered() []byte
- func (r Reader) Peek(max int) ([]byte, error)
- func (r Reader) Read(p []byte) (int, error)
- func (r Reader) ReadBytes(delimiter []byte, max int) ([]byte, bool, error)
- func (r Reader) ReadUTF8(max int) ([]rune, int, error)
- func (r Reader) WriteTo(w io.Writer) (int64, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrZeroAllocation is returned when the used pool returned a zero length byte slice. ErrZeroAllocation = errors.New("zero allocation") // ErrContentAbort is returned to the writer process in case of buffered content, when the reader // experienced an error. ErrContentAbort = errors.New("content pipe aborted") )
Functions ¶
This section is empty.
Types ¶
type ContentFunc ¶
ContentFunc wraps a function to implement the io.WriterTo interface. Function implementations should be reader to be executed in goroutines other than what they were created in.
type Options ¶
type Options struct {
// Pool defines the buffer pool to be used. It defaults to the pool created by DefaultPool(). It is
// expected to explicitly set the Pool instance, otherwise, not defining any globals, each Reader
// instance will create its own pool.
Pool Pool
}
Options provides options for the Reader.
type Pool ¶
type Pool interface {
// Get should return a non-zero length byte slice. In case it returns a zero length byte slice, or an
// explicit error, the read operations will fail.
//
// It is OK but not recommended to return varying sizes of byte slices.
Get() ([]byte, error)
// The reader always puts back the byte slices taken by Get, using Put.
Put([]byte)
}
Pool defines the interface for the used buffer pool. The buffered reader can be used either with the built-in default pool, noop pool, or with a custom pool implementation.
func DefaultPool ¶
DefultPool initializes a synchronized pool that stores and returns byte slices of allocSize length. It can be used with multiple readers concurrently.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader wraps an underlying io.Reader or io.WriterTo, and provides buffered io, via its methods. Initialize it via BufferedReader or BufferedContent.
It reads from the underlying source until the first error, but only returns an error when the buffer is empty. Once the underlying reader returned an error, it doesn't attempt to read from it anymore.
The reader does not support concurrent access.
func BufferedContent ¶
BufferedContent creates a buffered reader using the input content (io.WriterTo) as the underlying source.
It is similar to an io.Pipe, but with dynamic and pooled buffering internally. The individual Write calls are blocked until the reading side requests more data.
The provided WriterTo instances need to be safe to call in goroutines other than they were created in. The writer function returns with nil error, it will be interpreted as EOF on the reader side. When the reader side experiences an error, and the writer still has content to be written, the passed in io.Writer will return an ErrContentAbort error.
func BufferedReader ¶
BufferedReader creates a buffered reader using the input reader as the underlying source.
func (Reader) Buffered ¶
Buffered returns the buffered bytes.
The returned byte slice is not a copy of the buffered bytes, and therefore should not be modified.
func (Reader) Peek ¶
Peek returns at most max read bytes and keeps them buffered.
If the underlying reader returned an error, it returns an error when the underlying buffer was fully consumed by Read, ReadBytes, ReadUTF8 or WriteTo.
The returned byte slice is not a copy of the buffered bytes, and therefore should not be modified.
func (Reader) Read ¶
Read reads max len(p) copied to p and returns how many bytes were read.
It only returns an error when the buffer is empty. It only returns an error when the Pool.Get fails or the underlying reader returns an error.
It may return zero read length and nil error, but only if the underlying reader did so.
func (Reader) ReadBytes ¶
ReadBytes reads until the first occurence of delimiter in the input, within max length.
It returns the bytes, true and nil error, when the delimiter was found within max. In this case it consumes the buffer until and including the delimiter. If the underlying reader returned meanwhile a non-nil error, including EOF, it will be returned on subsequent reads, but only after the internal buffer was consumed.
It returns zero length bytes, false and nil error, when the delimiter was not found within max, and the underlying reader didn't return an error.
It returns max or less bytes, false and nil error, if the delimiter was not found within max, there are buffered bytes, the underlying reader returned an error. It consumes the returned bytes from the buffer. The delimiter may still be found in the remaining buffered bytes during subsequent calls.
It returns zero length bytes, false and non-nil error, if the buffer is empty and the underlying reader previously returned an error.
func (Reader) ReadUTF8 ¶
ReadUTF8 returns at most max UTF8 characters read from the underlying reader.
When valid UTF8 characters were found, it returns the characters, the number of bytes consumed, and nil error.
It only returns an error, including EOF, when the underlying buffer is empty.
It may return zero length characters and nil error, if the underlying reader returned zero length read with nil error.
It supports recovery of UTF8 streams by skipping the invalid characters. In such cases, first it returns the valid characters with the number of bytes consumed and nil error, then in the subsequent call, it returns zero characters, 1 and nil error.
Source Files