a generic object pool for golang
Go Shell
Switch branches/tags
Clone or download
dcormier Merge pull request #34 from dcormier/master
Updated documentation so examples show up properly
Latest commit 2633f27 Jun 21, 2018
Permalink
Failed to load latest commit information.
collections Only use context for canceling polling from queue Jun 19, 2018
concurrent Use only context for canceling conditions Jun 19, 2018
vendor/github.com add vendor to git repo. Aug 8, 2017
.gitignore add codecov support and remove circle. Aug 8, 2017
.travis.yml Support last two minor versions of golang (currently 1.9 and 1.10) Jun 4, 2018
LICENSE Initial commit Dec 28, 2015
README.md Follow go conventions for acronyms (all caps) Jun 21, 2018
config.go Follow go conventions for acronyms (all caps) Jun 21, 2018
config_test.go Follow go conventions for acronyms (all caps) Jun 21, 2018
example__simple_test.go Updated documentation so examples show up properly Jun 21, 2018
example_customFactory_test.go Updated documentation so examples show up properly Jun 21, 2018
example_multipleBorrowers_test.go Updated documentation so examples show up properly Jun 21, 2018
factory.go Improved examples Jun 20, 2018
factory_test.go Fixed typos Jun 21, 2018
glide.lock use glide to manage dependency. Aug 8, 2017
glide.yaml use glide to manage dependency. Aug 8, 2017
object.go Improved examples Jun 20, 2018
object_test.go Fixing linter warnings Jun 21, 2018
pool.go Updated documentation so examples show up properly Jun 21, 2018
pool_abandoned_test.go Fixing linter warnings Jun 21, 2018
pool_perf_test.go More changing from ints to time.Durations Jun 19, 2018
pool_test.go Fixing linter warnings Jun 21, 2018
test add codecov support and remove circle. Aug 8, 2017

README.md

Go Commons Pool

Build Status CodeCov Go Report Card GoDoc

The Go Commons Pool is a generic object pool for Golang, direct rewrite from Apache Commons Pool.

Features

  1. Support custom PooledObjectFactory.
  2. Rich pool configuration option, can precise control pooled object lifecycle. See ObjectPoolConfig.
    • Pool LIFO (last in, first out) or FIFO (first in, first out)
    • Pool cap config
    • Pool object validate config
    • Pool object borrow block and max waiting time config
    • Pool object eviction config
    • Pool object abandon config

Pool Configuration Option

Configuration option table, more detail description see ObjectPoolConfig

Option Default Description
LIFO true If pool is LIFO (last in, first out)
MaxTotal 8 The cap of pool
MaxIdle 8 Max "idle" instances in the pool
MinIdle 0 Min "idle" instances in the pool
TestOnCreate false Validate when object is created
TestOnBorrow false Validate when object is borrowed
TestOnReturn false Validate when object is returned
TestWhileIdle false Validate when object is idle, see TimeBetweenEvictionRuns
BlockWhenExhausted true Whether to block when the pool is exhausted
MinEvictableIdleTime 30m Eviction configuration,see DefaultEvictionPolicy
SoftMinEvictableIdleTime math.MaxInt64 Eviction configuration,see DefaultEvictionPolicy
NumTestsPerEvictionRun 3 The maximum number of objects to examine during each run evictor goroutine
TimeBetweenEvictionRuns 0 The number of milliseconds to sleep between runs of the evictor goroutine, less than 1 mean not run

Usage

import "github.com/jolestar/go-commons-pool"

//use create func
p := pool.NewObjectPoolWithDefaultConfig(pool.NewPooledObjectFactorySimple(
        func() (interface{}, error) {
            return &MyPoolObject{}, nil
        }))
obj, _ := p.BorrowObject()
p.ReturnObject(obj)

//use custom Object factory

type MyObjectFactory struct {
}

func (f *MyObjectFactory) MakeObject() (*pool.PooledObject, error) {
    return pool.NewPooledObject(&MyPoolObject{}), nil
}

func (f *MyObjectFactory) DestroyObject(object *PooledObject) error {
    //do destroy
    return nil
}

func (f *MyObjectFactory) ValidateObject(object *pool.PooledObject) bool {
    //do validate
    return true
}

func (f *MyObjectFactory) ActivateObject(object *pool.PooledObject) error {
    //do activate
    return nil
}

func (f *MyObjectFactory) PassivateObject(object *pool.PooledObject) error {
    //do passivate
    return nil
}

p := pool.NewObjectPoolWithDefaultConfig(new(MyObjectFactory))
p.Config.MaxTotal = 100
obj, _ := p.BorrowObject()
p.ReturnObject(obj)

For more examples please see pool_test.go and example_test.go.

Note

PooledObjectFactory.MakeObject must return a pointer, not value. The following code will complain error.

p := pool.NewObjectPoolWithDefaultConfig(pool.NewPooledObjectFactorySimple(
    func() (interface{}, error) {
        return "hello", nil
    }))
obj, _ := p.BorrowObject()
p.ReturnObject(obj)

The right way is:

p := pool.NewObjectPoolWithDefaultConfig(pool.NewPooledObjectFactorySimple(
    func() (interface{}, error) {
        s := "hello"
        return &s, nil
    }))

For more examples please see example_test.go.

Dependency

PerformanceTest

The results of running the pool_perf_test is almost equal to the java version PerformanceTest

go test --perf=true

For Apache commons pool user

  • Direct use pool.Config.xxx to change pool config
  • Default config value is same as java version
  • If TimeBetweenEvictionRuns changed after ObjectPool created, should call ObjectPool.StartEvictor to take effect. Java version do this on set method.
  • No KeyedObjectPool (TODO)
  • No ProxiedObjectPool
  • No pool stats (TODO)

FAQ

FAQ

How to contribute

  • Choose one open issue you want to solve, if not create one and describe what you want to change.
  • Fork the repository on GitHub.
  • Write code to solve the issue.
  • Create PR and link to the issue.
  • Make sure test and coverage pass.
  • Wait maintainers to merge.

中文文档

License

Go Commons Pool is available under the Apache License, Version 2.0.