pool

README

⭐   the project to show your appreciation. :arrow_upper_right:

A Better sync.Pool

This package is a thin wrapper over the Pool provided by the sync package. The Pool is an essential package to obtain maximum performance by reducing the number of memory allocations.

Extra Features

• Invalidate an item from the Pool (so it never gets used again)
• Set a maximum number of items for the Pool
• Returns the number of items in the pool (idle and in-use)

When should I use a pool?

If you frequently allocate many objects of the same type and you want to save some memory allocation and garbage allocation overhead — @jrv

How did I improve latency by 700% using sync.Pool

Example

import "github.com/rocketlaunchr/go-pool"

pool := pool.New(5) // maximum of 5 items in pool
pool.SetFactory(func() interface{} {
	return &X{}
})

item := pool.Borrow()
defer item.Return()

// Use item here or mark as invalid
x := item.Item.(*X) // Use item here
item.MarkAsInvalid()

Other useful packages

• awesome-svelte - Resources for killing react
• dataframe-go - Statistics and data manipulation
• dbq - Zero boilerplate database operations for Go
• electron-alert - SweetAlert2 for Electron Applications
• google-search - Scrape google search results
• igo - A Go transpiler with cool new syntax such as fordefer (defer for for-loops)
• mysql-go - Properly cancel slow MySQL queries
• react - Build front end applications using Go
• remember-go - Cache slow database queries
• testing-go - Testing framework for unit testing

Logo Credits

1. Renee French (gopher)
2. Samuel Jirénius (illustration)

Documentation

Index

• type ItemWrap
  • func (iw *ItemWrap) MarkAsInvalid()
  • func (iw *ItemWrap) Return()
• type Options
• type Pool
  • func New(opts ...interface{}) Pool
  • func (p *Pool) Borrow() *ItemWrap
  • func (p *Pool) Count() int
  • func (p *Pool) ReturnItem(x *ItemWrap)
  • func (p *Pool) SetFactory(factory func() interface{})

Types

type ItemWrap

type ItemWrap struct {
	Item interface{}
	// contains filtered or unexported fields
}

ItemWrap wraps the item returned by the pool's factory.

func (*ItemWrap) MarkAsInvalid

func (iw *ItemWrap) MarkAsInvalid()

MarkAsInvalid marks the item as invalid (eg. unusable, unstable or broken) so that after it gets put back in the pool, it is discarded. It will eventually get garbage collected.

func (*ItemWrap) Return

func (iw *ItemWrap) Return()

Return returns the item back to the pool.

type Options

type Options struct {
	// Initial creates an initial number of ready-to-use items in the pool.
	Initial int
	// Max sets the maximum number of items kept in the pool.
	Max *int
	// DisableCount, when set, disables the pool's Count function.
	// Only set this if you need a runtime Finalizer for the item returned
	// by the factory (alternatively, wrap your item in another struct, with the Finalizer
	// added to the original item).
	DisableCount bool
}

Options configures the Pool struct.

type Pool

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

A Pool is a set of temporary objects that may be individually saved and retrieved.

Any item stored in the Pool may be removed automatically at any time without notification. If the Pool holds the only reference when this happens, the item might be deallocated.

A Pool is safe for use by multiple goroutines simultaneously.

Pool's purpose is to cache allocated but unused items for later reuse, relieving pressure on the garbage collector. That is, it makes it easy to build efficient, thread-safe free lists. However, it is not suitable for all free lists.

An appropriate use of a Pool is to manage a group of temporary items silently shared among and potentially reused by concurrent independent clients of a package. Pool provides a way to amortize allocation overhead across many clients.

On the other hand, a free list maintained as part of a short-lived object is not a suitable use for a Pool, since the overhead does not amortize well in that scenario. It is more efficient to have such objects implement their own free list.

A Pool must not be copied after first use.

func New

func New(opts ...interface{}) Pool

New creates a new Pool. opts accepts either an int (representing the max) or an Options struct.

func (*Pool) Borrow

func (p *Pool) Borrow() *ItemWrap

Borrow obtains an item from the pool. If the Max option is set, then this function will block until an item is returned back into the pool.

After the item is no longer required, you must call Return on the item.

func (*Pool) Count

func (p *Pool) Count() int

Count returns approximately the number of items in the pool (idle and in-use). If you want an accurate number, call runtime.GC() twice before calling Count (not recommended).

func (*Pool) ReturnItem

func (p *Pool) ReturnItem(x *ItemWrap)

ReturnItem returns an item back to the pool. Usually this function is never called, as the recommended approach is to call Return on the item.

func (*Pool) SetFactory

func (p *Pool) SetFactory(factory func() interface{})

SetFactory specifies a function to generate an item when Borrow is called. It must not be called concurrently with calls to Borrow.

NOTE: factory should generally only return pointer types, since a pointer can be put into the return interface value without an allocation.