Skip to content
a generic object pool for golang
Go Shell
Branch: master
Clone or download
jolestar Merge pull request #43 from jolestar/evictconfig
when MinEvictableIdleTime  is zero or negative.
Latest commit 446f8cc May 26, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
collections Only use context for canceling polling from queue Jun 19, 2018
concurrent sync/atomic: addUint64 panics on ARM with unaligned pointers, refer to Apr 13, 2019
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 fix #36 Aug 30, 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 fix #38 when MinEvictableIdleTime is zero or negative. May 26, 2019
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 fix #38 when MinEvictableIdleTime is zero or negative. May 26, 2019
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

Use Simple Factory

import (
	"context"
	"fmt"
	"strconv"
	"sync/atomic"

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

func Example_simple() {
	type myPoolObject struct {
		s string
	}

	v := uint64(0)
	factory := pool.NewPooledObjectFactorySimple(
		func(context.Context) (interface{}, error) {
			return &myPoolObject{
					s: strconv.FormatUint(atomic.AddUint64(&v, 1), 10),
				},
				nil
		})

	ctx := context.Background()
	p := pool.NewObjectPoolWithDefaultConfig(ctx, factory)

	obj, err := p.BorrowObject(ctx)
	if err != nil {
		panic(err)
	}

	o := obj.(*myPoolObject)
	fmt.Println(o.s)

	err = p.ReturnObject(ctx, obj)
	if err != nil {
		panic(err)
	}

	// Output: 1
}

Use Custom Factory

import (
	"context"
	"fmt"
	"strconv"
	"sync/atomic"

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

type MyPoolObject struct {
	s string
}

type MyCustomFactory struct {
	v uint64
}

func (f *MyCustomFactory) MakeObject(ctx context.Context) (*pool.PooledObject, error) {
	return pool.NewPooledObject(
			&MyPoolObject{
				s: strconv.FormatUint(atomic.AddUint64(&f.v, 1), 10),
			}),
		nil
}

func (f *MyCustomFactory) DestroyObject(ctx context.Context, object *pool.PooledObject) error {
	// do destroy
	return nil
}

func (f *MyCustomFactory) ValidateObject(ctx context.Context, object *pool.PooledObject) bool {
	// do validate
	return true
}

func (f *MyCustomFactory) ActivateObject(ctx context.Context, object *pool.PooledObject) error {
	// do activate
	return nil
}

func (f *MyCustomFactory) PassivateObject(ctx context.Context, object *pool.PooledObject) error {
	// do passivate
	return nil
}

func Example_customFactory() {
	ctx := context.Background()
	p := pool.NewObjectPoolWithDefaultConfig(ctx, &MyCustomFactory{})
	p.Config.MaxTotal = 100
    
	obj1, err := p.BorrowObject(ctx)
	if err != nil {
		panic(err)
	}

	o := obj1.(*MyPoolObject)
	fmt.Println(o.s)

	err = p.ReturnObject(ctx, obj1)
	if err != nil {
		panic(err)
	}

	// Output: 1
}

For more examples please see pool_test.go and example_simple_test.go, example_customFactory_test.go.

Note

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

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

The right way is:

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

For more examples please see example_simple_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.

You can’t perform that action at this time.