README
¶
Package bbp provides efficient byte buffer pools with anti-memory-waste protection.
Byte buffers acquired from this package may be put back to the pool, but they do not need to; if they are returned, they will be recycled and reused, otherwise they will be garbage collected as usual.
The methods within this package and all Pool instances share the same
underlying sized byte slice pools. The byte buffers provided by this package
has a minimum limit of 64B and a maximum limit of 32MB,
byte slice with size not in the range will be allocated directly from Go runtime,
and won't be recycled for reuse.
Documentation
¶
Overview ¶
Package bbp provides efficient byte buffer pools with anti-memory-waste protection.
Byte buffers acquired from this package may be put back to the pool, but they do not need to; if they are returned, they will be recycled and reused, otherwise they will be garbage collected as usual.
The methods within this package and all `Pool` instances share the same underlying sized byte slice pools. The byte buffers provided by this package has a minimum limit of 64B and a maximum limit of 32MB, byte slice with size not in the range will be allocated directly from Go runtime, and won't be recycled for reuse.
Index ¶
- Constants
- func Get(length, capacity int) []byte
- func Grow(buf []byte, capacity int, reuseBuf bool) []byte
- func Put(buf []byte)
- func PutBuffer(buf *Buffer)
- type Buffer
- func (b *Buffer) Append(size int, f func([]byte) []byte)
- func (b *Buffer) Bytes() []byte
- func (b *Buffer) Clone() *Buffer
- func (b *Buffer) Copy() []byte
- func (b *Buffer) Grow(capacity int)
- func (b *Buffer) Len() int
- func (b *Buffer) ReadFrom(r io.Reader) (int64, error)
- func (b *Buffer) Reset()
- func (b *Buffer) Set(p []byte)
- func (b *Buffer) SetString(s string)
- func (b *Buffer) String() string
- func (b *Buffer) StringUnsafe() string
- func (b *Buffer) Write(p []byte) (int, error)
- func (b *Buffer) WriteByte(c byte) error
- func (b *Buffer) WriteRune(r rune) (n int, err error)
- func (b *Buffer) WriteString(s string) (int, error)
- func (b *Buffer) WriteStrings(s []string) (int, error)
- func (b *Buffer) WriteTo(w io.Writer) (int64, error)
- type Pool
- type Recorder
Constants ¶
const MinRead = 512
MinRead is the minimum slice size passed to a Read call by Buffer.ReadFrom.
Variables ¶
This section is empty.
Functions ¶
func Get ¶
Get returns a byte slice from the pool with specified length and capacity. When you finish the work with the buffer, you may call Put to put it back to the pool for reusing.
func Grow ¶
Grow returns a new byte buffer from the pool which is at least of specified capacity.
Note that if reuseBuf is true and a new slice is returned, the old buf will be put back to the pool, the caller must not retain reference to the buf and must not touch it after this calling returns, else data race happens.
Types ¶
type Buffer ¶
type Buffer struct {
// contains filtered or unexported fields
}
Buffer provides byte buffer, which can be used for minimizing memory allocations.
Buffer may be used with functions appending data to the underlying []byte slice. See example code for details.
Use NewBuffer for obtaining a buffer with specified capacity. The zero value for Buffer is an empty buffer ready to use.
func NewBuffer ¶
NewBuffer creates a new Buffer with specified capacity. When you finish the work with the buffer, you may call PutBuffer to put it back to the pool for reusing.
func (*Buffer) Append ¶ added in v2.5.0
Append accepts a function which append data to the underlying byte slice. `size` optionally indicates the possible size of data to append, it helps to pre-allocate enough memory.
func (*Buffer) Bytes ¶
Bytes returns the underlying byte slice, i.e. all the bytes accumulated in the buffer.
Note that this method doesn't copy the underlying byte slice, the caller should either copy the byte slice explicitly or don't return the Buffer back to the pool, otherwise data race will occur. You may use Buffer.Copy to get a copy of the underlying byte slice.
func (*Buffer) Clone ¶ added in v2.5.0
Clone returns a new copy of the buffer, including the underlying byte slice.
func (*Buffer) Grow ¶
Grow ensures that the underlying byte slice is at least of specified capacity.
func (*Buffer) ReadFrom ¶
ReadFrom implements io.ReaderFrom.
The function appends all the data read from r to b.
func (*Buffer) Set ¶
Set first re-slice the underlying byte slice to empty, then write p to the buffer.
func (*Buffer) StringUnsafe ¶
StringUnsafe is equivalent to String, but the string that it returns is _NOT_ copied, so modifying this buffer after calling StringUnsafe will lead to undefined behavior.
func (*Buffer) WriteByte ¶
WriteByte appends the byte c to the buffer.
The purpose of this function is bytes.Buffer compatibility.
The function always returns nil.
func (*Buffer) WriteRune ¶
WriteRune appends the UTF-8 encoding of Unicode code point r to the buffer.
The purpose of this function is bytes.Buffer compatibility.
The function always returns nil.
func (*Buffer) WriteString ¶
WriteString appends s to the underlying byte slice.
func (*Buffer) WriteStrings ¶
WriteStrings appends a slice of strings to the underlying byte slice.
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool is a byte buffer pool which reuses byte slice. It uses dynamic calibrating (which is a little atomic operations) to try best to match the workload.
Generally, if the size and capacity is known in advance, you may use the exported function Get(length, capacity) to get a properly sized byte buffer. However, if the buffer size is uncertain in advance, you may want to use this Pool. For different workloads, dedicated Pool instances are recommended, the dynamic calibrating will help to reduce memory waste.
All Pool instances share the same underlying sized byte slice pools. The byte buffers provided by Pool has a minimum limit of 64B and a maximum limit of 32MB, byte slice with size not in the range will be allocated directly from the operating system, and won't be recycled for reuse.
The zero value for Pool is ready to use. A Pool value shall not be copied after initialized.
func NewPool ¶
NewPool creates a new Pool instance using given Recorder.
In most cases, declaring a Pool variable is sufficient to initialize a Pool.
func (*Pool) Get ¶
Get returns a byte slice buffer from the pool. The returned buffer may be put back to the pool for reusing.
func (*Pool) GetBuffer ¶
GetBuffer returns a Buffer from the pool with dynamic calibrated default capacity. The returned Buffer may be put back to the pool for reusing.
type Recorder ¶
type Recorder struct {
// DefaultSize optionally configs the initial default size to be used.
// Default is 1024 bytes.
DefaultSize int
// CalibrateInterval optionally configs the interval to do calibrating.
// Default is 3 minutes.
CalibrateInterval time.Duration
// ResizePercentile optionally configs the percentile to reset the
// default size when doing calibrating, the value should be in range
// [50, 100). Default is 90.
ResizePercentile int
// contains filtered or unexported fields
}
Recorder helps to record most frequently used buffer size. It calibrates the recorded size data in running, thus it can dynamically adjust according to recent workload.
Source Files