buffer

package
v0.0.0-...-ab9d845 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 11, 2024 License: Apache-2.0, MIT Imports: 8 Imported by: 142

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

View Source
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

)
View Source
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

func MakeWithData(b []byte) Buffer

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

func MakeWithView(v *View) Buffer

MakeWithView creates a new Buffer initialized with given view. This function takes ownership of v.

func (*Buffer) Append

func (b *Buffer) Append(src *View) error

Append appends the given data. Append takes ownership of src.

func (*Buffer) Apply

func (b *Buffer) Apply(fn func(*View))

Apply applies the given function across all valid data.

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

func (b *Buffer) AsViewList() ViewList

AsViewList returns the ViewList backing b. Users may not save or modify the ViewList returned.

func (*Buffer) Checksum

func (b *Buffer) Checksum(offset int) uint16

Checksum calculates a checksum over the buffer's payload starting at offset.

func (*Buffer) Clone

func (b *Buffer) Clone() Buffer

Clone creates a copy-on-write clone of b. The underlying chunks are shared until they are written to.

func (*Buffer) DeepClone

func (b *Buffer) DeepClone() Buffer

DeepClone creates a deep clone of b, copying data such that no bytes are shared with any other Buffers.

func (*Buffer) Flatten

func (b *Buffer) Flatten() []byte

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

func (b *Buffer) GrowTo(length int64, zero bool)

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

func (b *Buffer) Merge(other *Buffer)

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) Prepend

func (b *Buffer) Prepend(src *View) error

Prepend prepends the given data. Prepend takes ownership of src.

func (*Buffer) PullUp

func (b *Buffer) PullUp(offset, length int) (View, bool)

PullUp makes the specified range contiguous and returns the backing memory.

func (*Buffer) ReadAt

func (b *Buffer) ReadAt(p []byte, offset int64) (int, error)

ReadAt implements io.ReaderAt.ReadAt.

func (*Buffer) ReadToWriter

func (b *Buffer) ReadToWriter(w io.Writer, count int64) (int64, error)

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) Release

func (b *Buffer) Release()

Release frees all resources held by b.

func (*Buffer) Size

func (b *Buffer) Size() int64

Size indicates the total amount of data available in this Buffer.

func (*Buffer) SubApply

func (b *Buffer) SubApply(offset, length int, fn func(*View))

SubApply applies fn to a given range of data in b. Any part of the range outside of b is ignored.

func (*Buffer) TrimFront

func (b *Buffer) TrimFront(count int64)

TrimFront removes the first count bytes from the buffer.

func (*Buffer) Truncate

func (b *Buffer) Truncate(length int64)

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

func (b *Buffer) WriteFromReader(r io.Reader, count int64) (int64, error)

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.

func (Range) Intersect

func (x Range) Intersect(y Range) Range

Intersect returns the intersection of x and y.

func (Range) Len

func (x Range) Len() int

Len returns the length of x.

func (Range) Offset

func (x Range) Offset(off int) Range

Offset returns x offset by off.

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

func NewView(cap int) *View

NewView creates a new view with capacity at least as big as cap. It is analogous to make([]byte, 0, cap).

func NewViewSize

func NewViewSize(size int) *View

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

func NewViewWithData(data []byte) *View

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) AsSlice

func (v *View) AsSlice() []byte

AsSlice returns a slice of the data written to this view.

func (*View) AvailableSize

func (v *View) AvailableSize() int

AvailableSize returns the number of bytes available for writing.

func (*View) BasePtr

func (v *View) BasePtr() *byte

BasePtr returns a pointer to the view's chunk.

func (*View) CapLength

func (v *View) CapLength(n int)

CapLength caps the length of the view's read slice to n. If n > v.Size(), the function is a no-op.

func (*View) Capacity

func (v *View) Capacity() int

Capacity returns the total size of this view's chunk.

func (*View) Clone

func (v *View) Clone() *View

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

func (v *View) Full() bool

Full indicates the chunk is full.

This indicates there is no capacity left to write.

func (*View) Grow

func (v *View) Grow(n int)

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) Read

func (v *View) Read(p []byte) (int, error)

Read reads v's data into p.

Implements the io.Reader interface.

func (*View) ReadAt

func (v *View) ReadAt(p []byte, off int) (int, error)

ReadAt reads data to the p starting at offset.

Implements the io.ReaderAt interface.

func (*View) ReadByte

func (v *View) ReadByte() (byte, error)

ReadByte implements the io.ByteReader interface.

func (*View) ReadFrom

func (v *View) ReadFrom(r io.Reader) (n int64, err error)

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) Size

func (v *View) Size() int

Size returns the size of data written to the view.

func (*View) ToSlice

func (v *View) ToSlice() []byte

ToSlice returns an owned copy of the data in this view.

func (*View) TrimFront

func (v *View) TrimFront(n int)

TrimFront advances the read index by the given amount.

func (*View) Write

func (v *View) Write(p []byte) (int, error)

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.

func (*View) WriteAt

func (v *View) WriteAt(p []byte, off int) (int, error)

WriteAt writes data to the views's chunk starting at start. If the view's chunk has a reference count greater than 1, the chunk is copied first and then written to.

Implements the io.WriterAt interface.

func (*View) WriteTo

func (v *View) WriteTo(w io.Writer) (n int64, err error)

WriteTo writes data to w until the view is empty or an error occurs. The return value n is the number of bytes written.

WriteTo implements the io.WriterTo interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL