README
¶
BytePool
A pool for []byte.
Usage:
The pool is thread-safe.
// create a pool of 16 items, each item has a size of 1024
var pool = bytepool.New(1024, 16)
bytes := pool.Checkout()
defer bytes.Release()
bytes.Write([]byte("hello"))
fmt.Prinltn(bytes.String())
Pool Growth
Getting an item from the pool is non-blocking. If the pool is depleted, a new item will be created. However, such dynamically created items are not added back to the pool on release. In other words, the # of items within the pool is fixed.
You can call the Depleted() method for count of how often the pool was depleted. If it's frequently greater than 0, consider increasing the count of items your pool holds.
Item Growth
Items are created with an initial size. Adding more data than this size will cause the item to internally and efficiently convert itself to a bytes.Buffer. However, the growth is not permanent: on Release the initial allocation is re-established (without needing to do a new allocation).
In other words, the total memory used by the bytepool should be size * count. For our above example, that's 16KB. The size will increase as needed, but will always revert back to 16KB (and that 16KB is only initiated once, on startup).
You can call the Expanded() method for a count of how often items were forced to grow beyond the initial size. If it's frequently greater than 0, consider increasing the initial size of the items.
Pool Methods:
New(size, count)- Creates a new pool ofcountitems, each initialize to holdsizebytes (but able to grow as needed)Checkout() *Bytes- Gets a item which you can write/read fromDepleted() int64- How often the pool was empty. Calling this resets the counterExpanded() int64- How often items were forced to grow beyond their initial size. Calling this resets the counterStats() map[string]int64-DepletedandExpandedin a map
Item Methods:
Write(data []byte) (n int, err error)WriteByte(data byte) errorWriteString(data string) (n int, err error)Bytes() []byteString() stringLen() intReadFrom(r io.Reader) (n int64, err error)ReadNFrom(n int64, r io.Reader) (m int64, err error)Read(data []byte) (int, error)Release()orClose()- Resets and releases the item back to the pool.Reset()- Resets the item without releasing it back to the poolPosition(n uint)- Moves to the specified absolute position. This will grow the buffer if needed.
Numeric Encoding
The WriteUint16, WriteUint32 and WriteUint64 methods can be used to write integers
in big endian.
To write using little endian, create a pool using NewEndian or an individual item using NewEndianBytes and pass the binary.LittleEndian object from the stdlib "encoding/binary" package.
Corresponding ReadUint16, ReadUint32 and ReadUint64 are availabl. They return (n, error) where error will be io.EOF if not enough data is available.
Each
It's possible to pre-fill byte items within the pool through the use of the pool's Each and the item's Position functions. You have to take special care to properly Position the item on each checkout.
If you pre-fill the item with more data than the initial capacity, the data will be lost. It makes no sense that you'd define a pool with items having a capacity of 50 bytes., but pre-fill 100 bytes.
For example, say we were writing into a buffer where bytes 4-8 were always the value 30, we could do:
//setup
pool := bytepool.New(256, 10)
pool.Each(func(b *bytepool.Bytes) {
b.Position(4)
b.WriteInt32(30)
})
// code that uses the buffer
bytes := pool.Checkout()
bytes.WriteInt32(size) //write into bytes[0:4]
bytes.Position(8) //skip bytes[4:8] which we already filled
//continue
Documentation
¶
Overview ¶
Package bytepool provides a pool of []byte
Index ¶
- type Bytes
- func (b *Bytes) Close() error
- func (b *Bytes) Position(n uint)
- func (b *Bytes) ReadByte() (byte, error)
- func (b *Bytes) ReadFrom(r io.Reader) (n int64, err error)
- func (b *Bytes) ReadNFrom(n int64, r io.Reader) (m int64, err error)
- func (b *Bytes) ReadUint16() (uint16, error)
- func (b *Bytes) ReadUint32() (uint32, error)
- func (b *Bytes) ReadUint64() (uint64, error)
- func (b *Bytes) Release()
- func (b *Bytes) Reset()
- func (b *Bytes) SetOnExpand(callback func())
- func (b *Bytes) Write(data []byte) (n int, err error)
- func (b *Bytes) WriteByte(d byte) (err error)
- func (b *Bytes) WriteString(str string) (int, error)
- func (b *Bytes) WriteUint16(n uint16)
- func (b *Bytes) WriteUint32(n uint32)
- func (b *Bytes) WriteUint64(n uint64)
- type Pool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bytes ¶
type Bytes struct {
// contains filtered or unexported fields
}
func (*Bytes) ReadUint16 ¶
func (*Bytes) ReadUint32 ¶
func (*Bytes) ReadUint64 ¶
func (*Bytes) SetOnExpand ¶
func (b *Bytes) SetOnExpand(callback func())
Set a custom OnExpand callback (overwriting the one already set). Only useful for when NewBytes is called directly as opposed to through the pool.
func (*Bytes) WriteUint16 ¶
func (*Bytes) WriteUint32 ¶
func (*Bytes) WriteUint64 ¶
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
func New ¶
Create a new pool. The pool contains count items. Each item allocates an array of size bytes (but can dynamically grow)
func (*Pool) Depleted ¶
Get a count of how often Checkout() was called but no item was available (thus causing an item to be created on the fly) Calling this resets the counter
func (*Pool) Each ¶
Exposes every item currently in the pool If an item is checkout, each won't see it. As such, though thread-safe, you probably only want to call this method on init/startup.
Source Files