pool

README

pool

Tiny memory reuse helpers for Go.

generic

Without use of subpackages, pool allows to reuse any struct distinguishable by size in generic way:

package main

import "github.com/gobwas/pool"

func main() {
	x, n := pool.Get(100) // Returns object with size 128 or nil.
	if x == nil {
		// Create x somehow with knowledge that n is 128.
	}
	defer pool.Put(x, n)
	
	// Work with x.
}

Pool allows you to pass specific options for constructing custom pool:

package main

import "github.com/gobwas/pool"

func main() {
	p := pool.Custom(
        pool.WithLogSizeMapping(),      // Will ceil size n passed to Get(n) to nearest power of two.
        pool.WithLogSizeRange(64, 512), // Will reuse objects in logarithmic range [64, 512].
        pool.WithSize(65536),           // Will reuse object with size 65536.
    )
	x, n := p.Get(1000)  // Returns nil and 1000 because mapped size 1000 => 1024 is not reusing by the pool.
    defer pool.Put(x, n) // Will not reuse x.
	
	// Work with x.
}

Note that there are few non-generic pooling implementations inside subpackages.

pbytes

Subpackage pbytes is intended for []byte reuse.

package main

import "github.com/gobwas/pool/pbytes"

func main() {
	bts := pbytes.GetCap(100) // Returns make([]byte, 0, 128).
	defer pbytes.Put(bts)

	// Work with bts.
}

You can also create your own range for pooling:

package main

import "github.com/gobwas/pool/pbytes"

func main() {
	// Reuse only slices whose capacity is 128, 256, 512 or 1024.
	pool := pbytes.New(128, 1024) 

	bts := pool.GetCap(100) // Returns make([]byte, 0, 128).
	defer pool.Put(bts)

	// Work with bts.
}

pbufio

Subpackage pbufio is intended for *bufio.{Reader, Writer} reuse.

package main

import "github.com/gobwas/pool/pbufio"

func main() {
	bw := pbufio.GetWriter(os.Stdout, 100) // Returns bufio.NewWriterSize(128).
	defer pbufio.PutWriter(bw)

	// Work with bw.
}

Like with pbytes, you can also create pool with custom reuse bounds.

Documentation

Overview

Package pool contains helpers for pooling structures distinguishable by size.

Quick example:

import "github.com/gobwas/pool"

func main() {
   // Reuse objects in logarithmic range from 0 to 64 (0,1,2,4,6,8,16,32,64).
   p := pool.New(0, 64)

   buf, n := p.Get(10) // Returns buffer with 16 capacity.
   if buf == nil {
       buf = bytes.NewBuffer(make([]byte, n))
   }
   defer p.Put(buf, n)

   // Work with buf.
}

There are non-generic implementations for pooling: - pool/pbytes for []byte reuse; - pool/pbufio for *bufio.Reader and *bufio.Writer reuse;

Index

• Variables
• func Get(size int) (interface{}, int)
• func Put(x interface{}, size int)
• type Config
• type Option
  • func WithIdentitySizeMapping() Option
  • func WithLogSizeMapping() Option
  • func WithLogSizeRange(min, max int) Option
  • func WithSize(n int) Option
  • func WithSizeMapping(sz func(int) int) Option
• type Pool
  • func Custom(opts ...Option) *Pool
  • func New(min, max int) *Pool
  • func (p *Pool) Get(size int) (interface{}, int)
  • func (p *Pool) Put(x interface{}, size int)

Variables

var DefaultPool = New(128, 65536)

Functions

func Get

func Get(size int) (interface{}, int)

Get pulls object whose generic size is at least of given size. It also returns a real size of x for further pass to Put(). It returns -1 as real size for nil x. Size >-1 does not mean that x is non-nil, so checks must be done.

Note that size could be ceiled to the next power of two.

Get is a wrapper around DefaultPool.Get().

func Put

func Put(x interface{}, size int)

Put takes x and its size for future reuse. Put is a wrapper around DefaultPool.Put().

Types

type Config

type Config interface {
	AddSize(n int)
	SetSizeMapping(func(int) int)
}

Config describes generic pool configuration.

type Option

type Option func(Config)

Option configures pool.

func WithIdentitySizeMapping

func WithIdentitySizeMapping() Option

func WithLogSizeMapping

func WithLogSizeMapping() Option

func WithLogSizeRange

func WithLogSizeRange(min, max int) Option

WithSizeLogRange returns an Option that will add logarithmic range of pooling sizes containing [min, max] values.

func WithSize

func WithSize(n int) Option

WithSize returns an Option that will add given pooling size to the pool.

func WithSizeMapping

func WithSizeMapping(sz func(int) int) Option

type Pool

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

Pool contains logic of reusing objects distinguishable by size in generic way.

func Custom

func Custom(opts ...Option) *Pool

Custom creates new Pool with given options.

func New

func New(min, max int) *Pool

New creates new Pool that reuses objects which size is in logarithmic range [min, max].

Note that it is a shortcut for Custom() constructor with Options provided by WithLogSizeMapping() and WithLogSizeRange(min, max) calls.

func (*Pool) Get

func (p *Pool) Get(size int) (interface{}, int)

Get pulls object whose generic size is at least of given size. It also returns a real size of x for further pass to Put() even if x is nil. Note that size could be ceiled to the next power of two.

func (*Pool) Put

func (p *Pool) Put(x interface{}, size int)

Put takes x and its size for future reuse.