pool

README

Pool

This is a wrapper over standard sync.Pool which solves few problems:

• automatically provides Release() logic with the following features:
  • protect against retuning the object back to the pool twice accidentally
  • automatic cleanup before release if Cleanup() struct func is defined
• automatic init after borrow if Init() struct funcs is defined
• automatic lifetime control of owned objects: owned object can not be released manually. Automaticaly will be released on owner release only
• debug tools
  • GetObjectsInUse(). Very useful to have require.Zero(t, pool.GetObjectsInUse()) at the end of each test
  • tracking of code points where an object was borrowed but not returned back to the pool (in debug mode only). Call pool.PrintNonReleased(os.Stdout) at the end of your test to catch leaks
  • easy to switch off pooling for debug purposes: just use NewPoolStub() instead of NewPool() and the pool will not actually be used, i.e. new entity will be created on each IPool.Get()

Install

go get https://github.com/host6/pool

Usage

• see basic usage test

Documentation

Index

• func GetObjectsInUse() uint64
• func PrintNonReleased(w io.Writer)
• func RegisterObjectsInUseCounter(oc func() uint64)
• func SetDebug(IsDebug bool)
• type IPool
  • func NewPool[T any](instantiator func(releaser IReleaser) any) IPool[T]
  • func NewPoolStub[T any](instantiator func(releaser IReleaser) any) IPool[T]
• type IReleaser

Functions

func GetObjectsInUse

func GetObjectsInUse() uint64

GetObjectsInUse returns total amount of objects taken from all pools but not returned useful in tests

func PrintNonReleased

func PrintNonReleased(w io.Writer)

PrintNonReleased prints stacktraces that explains where non-released objects were borrowed note: debug mode must be turned on by `pool.SetDebug(true)` call

func RegisterObjectsInUseCounter

func RegisterObjectsInUseCounter(oc func() uint64)

RegisterObjectsInUseCounter registers pooled objects counter which will be considered by GetObjectsInUse() called automatically on each NewPool() to track the new pool useful if e.g. we have different pool somewhere else it is useful to register its counter here and use pool.GetObjectsInUse() only as a single pooled objects counter note: func counter must be thread-safe

func SetDebug

func SetDebug(IsDebug bool)

SetDebug switches debug mode. In debug mode pool engine tracks amounts of non-released objects per each borrow source code point (for all pools) use PrintNonReleased() to get explanations useful for investigations only, decreases performance

Types

type IPool

type IPool[T any] interface {
	Get() T

	// borrows an object from pool which can be released by releaser func only. obj.Release() causes panic.
	// use case: pooled root object owns a nested pooled object. Borrow nested by GetOwned to avoid nested release before root release
	GetOwned(owner IReleaser) T
}

IPool s.e. use NewPool() and NewPoolStub()

func NewPool

func NewPool[T any](instantiator func(releaser IReleaser) any) IPool[T]

func NewPoolStub

func NewPoolStub[T any](instantiator func(releaser IReleaser) any) IPool[T]

NewPoolStub creates pool which does not act as a pool. I.e. just creates a new instance on each Get() Release() does nothing more but Cleaunp() call if it exists does not track borrow source code points in debug mode useful for investigations

type IReleaser

type IReleaser interface {
	// Release returns the owner instance to the pool
	// panics if released already avoiding returning the same object to the pool twice
	// calls owner's Cleanup() if exists before returning to pool
	Release()
	IsOwned() bool
	// contains filtered or unexported methods
}

IReleaser provides ability to return the instance which holds the IReleaser to the pool owner instance must set its internal IReleaser to the implementation obtained from the pool see NewPool() instantiator argument