Documentation
¶
Overview ¶
Package buffer provides the implementation of a non-contiguous buffer that is reference counted, pooled, and copy-on-write. It allows O(1) append, and prepend operations.
Index ¶
- Constants
- type Buffer
- func (b *Buffer) Append(src *View) error
- func (b *Buffer) Apply(fn func(*View))
- func (b *Buffer) AsBufferReader() BufferReader
- func (b *Buffer) AsViewList() ViewList
- func (b *Buffer) Checksum(offset int) uint16
- func (b *Buffer) Clone() Buffer
- func (b *Buffer) DeepClone() Buffer
- func (b *Buffer) Flatten() []byte
- func (b *Buffer) GrowTo(length int64, zero bool)
- func (b *Buffer) Merge(other *Buffer)
- func (b *Buffer) Prepend(src *View) error
- func (b *Buffer) PullUp(offset, length int) (View, bool)
- func (b *Buffer) ReadAt(p []byte, offset int64) (int, error)
- func (b *Buffer) ReadToWriter(w io.Writer, count int64) (int64, error)
- func (b *Buffer) Release()
- func (b *Buffer) Size() int64
- func (b *Buffer) StateFields() []string
- func (b *Buffer) StateLoad(ctx context.Context, stateSourceObject state.Source)
- func (b *Buffer) StateSave(stateSinkObject state.Sink)
- func (b *Buffer) StateTypeName() string
- func (b *Buffer) SubApply(offset, length int, fn func(*View))
- func (b *Buffer) TrimFront(count int64)
- func (b *Buffer) Truncate(length int64)
- func (b *Buffer) WriteFromReader(r io.Reader, count int64) (int64, error)
- func (b *Buffer) WriteFromReaderAndLimitedReader(r io.Reader, count int64, lr *io.LimitedReader) (int64, error)
- type BufferReader
- type Range
- type View
- func (v *View) AsSlice() []byte
- func (v *View) AvailableSize() int
- func (v *View) BasePtr() *byte
- func (v *View) CapLength(n int)
- func (v *View) Capacity() int
- func (v *View) Clone() *View
- func (v *View) Full() bool
- func (v *View) Grow(n int)
- func (v *View) Read(p []byte) (int, error)
- func (v *View) ReadAt(p []byte, off int) (int, error)
- func (v *View) ReadByte() (byte, error)
- func (v *View) ReadFrom(r io.Reader) (n int64, err error)
- func (v *View) Release()
- func (v *View) Reset()
- func (v *View) Size() int
- func (v *View) StateFields() []string
- func (v *View) StateLoad(ctx context.Context, stateSourceObject state.Source)
- func (v *View) StateSave(stateSinkObject state.Sink)
- func (v *View) StateTypeName() string
- func (v *View) ToSlice() []byte
- func (v *View) TrimFront(n int)
- func (v *View) Write(p []byte) (int, error)
- func (v *View) WriteAt(p []byte, off int) (int, error)
- func (v *View) WriteTo(w io.Writer) (n int64, err error)
- type ViewElementMapper
- type ViewEntry
- func (e *ViewEntry) Next() *View
- func (e *ViewEntry) Prev() *View
- func (e *ViewEntry) SetNext(elem *View)
- func (e *ViewEntry) SetPrev(elem *View)
- func (e *ViewEntry) StateFields() []string
- func (e *ViewEntry) StateLoad(ctx context.Context, stateSourceObject state.Source)
- func (e *ViewEntry) StateSave(stateSinkObject state.Sink)
- func (e *ViewEntry) StateTypeName() string
- type ViewList
- func (l *ViewList) Back() *View
- func (l *ViewList) Empty() bool
- func (l *ViewList) Front() *View
- func (l *ViewList) InsertAfter(b, e *View)
- func (l *ViewList) InsertBefore(a, e *View)
- func (l *ViewList) Len() (count int)
- func (l *ViewList) PushBack(e *View)
- func (l *ViewList) PushBackList(m *ViewList)
- func (l *ViewList) PushFront(e *View)
- func (l *ViewList) PushFrontList(m *ViewList)
- func (l *ViewList) Remove(e *View)
- func (l *ViewList) Reset()
- func (l *ViewList) StateFields() []string
- func (l *ViewList) StateLoad(ctx context.Context, stateSourceObject state.Source)
- func (l *ViewList) StateSave(stateSinkObject state.Sink)
- func (l *ViewList) StateTypeName() string
Constants ¶
const ( // MaxChunkSize is largest payload size that we pool. Payloads larger than // this will be allocated from the heap and garbage collected as normal. MaxChunkSize = baseChunkSize << (numPools - 1) // 64k )
const ReadSize = 512
ReadSize is the default amount that a View's size is increased by when an io.Reader has more data than a View can hold during calls to ReadFrom.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Buffer ¶
type Buffer struct {
// contains filtered or unexported fields
}
Buffer is a non-linear buffer.
+stateify savable
func MakeWithData ¶
MakeWithData creates a new Buffer initialized with given data. This function should be used with caution to avoid unnecessary []byte allocations. When in doubt use NewWithView to maximize chunk reuse.
func MakeWithView ¶
MakeWithView creates a new Buffer initialized with given view. This function takes ownership of v.
func (*Buffer) AsBufferReader ¶
func (b *Buffer) AsBufferReader() BufferReader
AsBufferReader returns the Buffer as a BufferReader capable of io methods. The new BufferReader takes ownership of b.
func (*Buffer) AsViewList ¶
AsViewList returns the ViewList backing b. Users may not save or modify the ViewList returned.
func (*Buffer) Checksum ¶
Checksum calculates a checksum over the buffer's payload starting at offset.
func (*Buffer) Clone ¶
Clone creates a copy-on-write clone of b. The underlying chunks are shared until they are written to.
func (*Buffer) DeepClone ¶
DeepClone creates a deep clone of b, copying data such that no bytes are shared with any other Buffers.
func (*Buffer) Flatten ¶
Flatten returns a flattened copy of this data.
This method should not be used in any performance-sensitive paths. It may allocate a fresh byte slice sufficiently large to contain all the data in the buffer. This is principally for debugging.
N.B. Tee data still belongs to this Buffer, as if there is a single buffer present, then it will be returned directly. This should be used for temporary use only, and a reference to the given slice should not be held.
func (*Buffer) GrowTo ¶
GrowTo grows the given Buffer to the number of bytes, which will be appended. If zero is true, all these bytes will be zero. If zero is false, then this is the caller's responsibility.
Precondition: length must be >= 0.
func (*Buffer) Merge ¶
Merge merges the provided Buffer with this one.
The other Buffer will be appended to v, and other will be empty after this operation completes.
func (*Buffer) ReadToWriter ¶
ReadToWriter reads from the buffer into an io.Writer.
N.B. This does not consume the bytes read. TrimFront should be called appropriately after this call in order to do so.
func (*Buffer) StateFields ¶
func (*Buffer) StateTypeName ¶
func (*Buffer) SubApply ¶
SubApply applies fn to a given range of data in b. Any part of the range outside of b is ignored.
func (*Buffer) Truncate ¶
Truncate truncates the Buffer to the given length.
This will not grow the Buffer, only shrink it. If a length is passed that is greater than the current size of the Buffer, then nothing will happen.
Precondition: length must be >= 0.
func (*Buffer) WriteFromReader ¶
WriteFromReader writes to the buffer from an io.Reader. A maximum read size of MaxChunkSize is enforced to prevent allocating views from the heap.
func (*Buffer) WriteFromReaderAndLimitedReader ¶
func (b *Buffer) WriteFromReaderAndLimitedReader(r io.Reader, count int64, lr *io.LimitedReader) (int64, error)
WriteFromReaderAndLimitedReader is the same as WriteFromReader, but optimized to avoid allocations if a LimitedReader is passed in.
This function clobbers the values of lr.
type BufferReader ¶
type BufferReader struct {
// contains filtered or unexported fields
}
BufferReader implements io methods on Buffer. Users must call Close() when finished with the buffer to free the underlying memory.
func (*BufferReader) Close ¶
func (br *BufferReader) Close()
Close implements the io.Closer interface.
func (*BufferReader) Len ¶
func (br *BufferReader) Len() int
Len returns the number of bytes in the unread portion of the buffer.
func (*BufferReader) Read ¶
func (br *BufferReader) Read(p []byte) (int, error)
Read implements the io.Reader interface.
func (*BufferReader) ReadByte ¶
func (br *BufferReader) ReadByte() (byte, error)
ReadByte implements the io.ByteReader interface.
type Range ¶
type Range struct {
// contains filtered or unexported fields
}
Range specifies a range of buffer.
type View ¶
type View struct {
ViewEntry `state:"nosave"`
// contains filtered or unexported fields
}
View is a window into a shared chunk. Views are held by Buffers in viewLists to represent contiguous memory.
A View must be created with NewView, NewViewWithData, or Clone. Owners are responsible for maintaining ownership over their views. When Views need to be shared or copied, the owner should create a new View with Clone. Clone must only ever be called on a owned View, not a borrowed one.
Users are responsible for calling Release when finished with their View so that its resources can be returned to the pool.
Users must not write directly to slices returned by AsSlice. Instead, they must use Write/WriteAt/CopyIn to modify the underlying View. This preserves the safety guarantees of copy-on-write.
+stateify savable
func NewView ¶
NewView creates a new view with capacity at least as big as cap. It is analogous to make([]byte, 0, cap).
func NewViewSize ¶
NewViewSize creates a new view with capacity at least as big as size and length that is exactly size. It is analogous to make([]byte, size).
func NewViewWithData ¶
NewViewWithData creates a new view and initializes it with data. This function should be used with caution to avoid unnecessary []byte allocations. When in doubt use NewWithView to maximize chunk reuse in production environments.
func (*View) AvailableSize ¶
AvailableSize returns the number of bytes available for writing.
func (*View) CapLength ¶
CapLength caps the length of the view's read slice to n. If n > v.Size(), the function is a no-op.
func (*View) Clone ¶
Clone creates a shallow clone of v where the underlying chunk is shared.
The caller must own the View to call Clone. It is not safe to call Clone on a borrowed or shared View because it can race with other View methods.
func (*View) Full ¶
Full indicates the chunk is full.
This indicates there is no capacity left to write.
func (*View) Grow ¶
Grow increases the size of the view. If the new size is greater than the view's current capacity, Grow will reallocate the view with an increased capacity.
func (*View) ReadAt ¶
ReadAt reads data to the p starting at offset.
Implements the io.ReaderAt interface.
func (*View) ReadFrom ¶
ReadFrom reads data from r until EOF and appends it to the buffer, growing the buffer as needed. The return value n is the number of bytes read. Any error except io.EOF encountered during the read is also returned.
ReadFrom implements the io.ReaderFrom interface.
func (*View) Release ¶
func (v *View) Release()
Release releases the chunk held by v and returns v to the pool.
func (*View) Reset ¶
func (v *View) Reset()
Reset sets the view's read and write indices back to zero.
func (*View) StateFields ¶
func (*View) StateTypeName ¶
func (*View) Write ¶
Write writes data to the view's chunk starting at the v.write index. If the view's chunk has a reference count greater than 1, the chunk is copied first and then written to.
Implements the io.Writer interface.
type ViewElementMapper ¶
type ViewElementMapper struct{}
ElementMapper provides an identity mapping by default.
This can be replaced to provide a struct that maps elements to linker objects, if they are not the same. An ElementMapper is not typically required if: Linker is left as is, Element is left as is, or Linker and Element are the same type.
type ViewEntry ¶
type ViewEntry struct {
// contains filtered or unexported fields
}
Entry is a default implementation of Linker. Users can add anonymous fields of this type to their structs to make them automatically implement the methods needed by List.
+stateify savable
func (*ViewEntry) StateFields ¶
func (*ViewEntry) StateTypeName ¶
type ViewList ¶
type ViewList struct {
// contains filtered or unexported fields
}
List is an intrusive list. Entries can be added to or removed from the list in O(1) time and with no additional memory allocations.
The zero value for List is an empty list ready to use.
To iterate over a list (where l is a List):
for e := l.Front(); e != nil; e = e.Next() {
// do something with e.
}
+stateify savable
func (*ViewList) InsertAfter ¶
InsertAfter inserts e after b.
func (*ViewList) InsertBefore ¶
InsertBefore inserts e before a.
func (*ViewList) Len ¶
Len returns the number of elements in the list.
NOTE: This is an O(n) operation.
func (*ViewList) PushBackList ¶
PushBackList inserts list m at the end of list l, emptying m.
func (*ViewList) PushFrontList ¶
PushFrontList inserts list m at the start of list l, emptying m.
Source Files