rebytes

README

Rebytes – Recycled byte slice pool and buffer for Golang

Synopsis

    // Byte slice pool with 1k slice capacity, 100 pool capacity
    pool := rebytes.NewPool(1024, 100)
    byteSlice := pool.Get()
    pool.Put(byteSlice)

    // Like bytes.Buffer, but with dynamic memory managed by the pool
    buf, err := rebytes.NewBuffer(pool)
    buf.WriteString("Hello World")

Status

This software is considered ALPHA quality. Not recommended for production use.

Description

Package rebytes provides types that recycle bytes slices to reduce allocation and garbage collection:

• rebytes.Pool: a []byte pool that provides/recycles fixed capacity slices from a fixed-maximum-size pool.
• rebytes.Buffer: a bytes.Buffer analogue that dynamically gets/returns memory from a rebytes.Pool.

Copyright and License

Copyright 2017 by David A. Golden. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Documentation

Overview

Package rebytes provides types that recycle bytes slices to reduce allocation and garbage collection.

Index

• Variables
• type Buffer
  • func NewBuffer(pool *Pool) (*Buffer, error)
  • func (b *Buffer) Chunks() int
  • func (b *Buffer) Free()
  • func (b *Buffer) Read(p []byte) (n int, err error)
  • func (b *Buffer) ReadAt(p []byte, off int64) (n int, err error)
  • func (b *Buffer) String() string
  • func (b *Buffer) Write(p []byte) (n int, err error)
  • func (b *Buffer) WriteString(s string) (n int, err error)
• type Pool
  • func NewPool(bytesCap, poolCap int) *Pool
  • func (p *Pool) Get() []byte
  • func (p *Pool) Put(b []byte) error
  • func (p *Pool) Size() int

Variables

var ErrTooLarge = errors.New("rebytes.Buffer: too large")

ErrTooLarge is passed to panic if memory cannot be allocated to store data in a buffer.

Types

type Buffer

type Buffer struct {
	// contains filtered or unexported fields
}

Buffer is a dynamic buffer of bytes satisfying the Reader and Writer interfaces. Memory is managed by a rebytes.Pool: new memory is allocated from the pool as needed for writign and returned to the pool after reading.

func NewBuffer

func NewBuffer(pool *Pool) (*Buffer, error)

NewBuffer creates a new buffer from a rebytes.Pool. It only errors if passed nil.

func (*Buffer) Chunks

func (b *Buffer) Chunks() int

Chunks returns the number of []byte chunks used by the buffer.

func (*Buffer) Free

func (b *Buffer) Free()

Free recycles byte slices back into the associated pool. The buffer is unusable afterwards.

func (*Buffer) Read

func (b *Buffer) Read(p []byte) (n int, err error)

Read reads the next len(p) unread bytes into p. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered. When there is too-little data to fill p, the error will be io.EOF.

func (*Buffer) ReadAt

func (b *Buffer) ReadAt(p []byte, off int64) (n int, err error)

ReadAt reads len(p) bytes into p starting at offset off in the buffer. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered. When there is too-little data to fill p, the error will be io.EOF.

func (*Buffer) String

func (b *Buffer) String() string

String joins unread []byte chunks into single string

func (*Buffer) Write

func (b *Buffer) Write(p []byte) (n int, err error)

Write appends the contents of p to the buffer, growing the buffer as needed. The return value n is the length of p; err is always nil. If the buffer becomes too large, Write will panic with ErrTooLarge.

func (*Buffer) WriteString

func (b *Buffer) WriteString(s string) (n int, err error)

WriteString appends the contents of s to the buffer, growing the buffer as needed. The return value n is the length of s; err is always nil. If the buffer becomes too large, Write will panic with ErrTooLarge.

type Pool

type Pool struct {
	// contains filtered or unexported fields
}

Pool represents a goroutine-safe pool of []byte values of a configurable capacity. Because it contains a sync.Mutex, it must not be copied.

func NewPool

func NewPool(bytesCap, poolCap int) *Pool

NewPool constructs a new pool of []byte. The first argument is the capacity for []byte values retrieved from the pool. The second argument is the maximum number of unused []byte values that can be stored in the pool.

func (*Pool) Get

func (p *Pool) Get() []byte

Get returns a []byte with zero length and the pool's configured []byte capacity. The []byte value is removed from the pool if available or constructed on the spot otherwise.

func (*Pool) Put

func (p *Pool) Put(b []byte) error

Put places a []byte into the pool. The pool takes ownership and the provided []byte MUST NOT be used again until returned from the pool with Get(). The []byte is resliced to zero length. NOTE: data is not zeroed out, only the length.

If the argument is nil or is a []byte with a capacity that isn't the same as the pool's configured []byte capacity, an error is returned and the argument is not added to the pool.

func (*Pool) Size

func (p *Pool) Size() int

Size returns the number of []byte values in the pool.