pond

README

Pond

Generic Object Pool for Golang.

Adopters

• Hive: A high-efficiency Goroutine Pool.

Get Started

type conn struct {
    addr string
}

ctx := context.Background()
cfg := pond.NewDefaultConfig()
//required
cfg.ObjectCreateFactory = func (ctx context.Context) (interface{}, error) {
    return &conn{addr: "127.0.0.1"}, nil
}
//optional
cfg.ObjectValidateFactory = func (ctx context.Context, object interface{}) bool {
    c := object.(*conn)
    return c.addr != ""
}
//optional
cfg.ObjectDestroyFactory = func (ctx context.Context, object interface{}) error {
    c := object.(*conn)
    c.addr = ""
    return nil
}

p, err := pond.New(cfg)
if err != nil {
    log.Fatal(err)
}

obj, err := p.BorrowObject(ctx)
if err != nil {
    log.Fatal(err)
}
defer p.ReturnObject(ctx, obj)
fmt.Printf("get conn: %v\n", obj.(*conn).addr)

Configuration

Option	Default	Description
MaxSize	10	The capacity of the pool. If MaxSize <= 0, no capacity limit.
MinIdle	0	The minimum size of the idle objects.
MaxIdle	10	The maximal size of the idle objects. Idle objects exceeding MaxIdle will be evicted.
MinIdleTime	5m	The minimum time that idle object should be reserved.
Nonblocking	false	The blocking policy. If true, it will return ErrPoolExhausted when pool is exhausted.
AutoEvict	true	Enable auto evict idle objects. When true, pool will create a goroutine to start a evictor.
EvictInterval	30s	The interval between evict.
MaxValidateAttempts	1	The maximal attempts to validate object.
ObjectCreateFactory	required	The factory of creating object.
ObjectValidateFactory	none	The factory of validating object.
ObjectDestroyFactory	none	The factory of destroying object.

Benchmark

Compare with:

• go-commons-pool:

BenchmarkPool-8                          3116902               358 ns/op              71 B/op          2 allocs/op
BenchmarkPoolWithConcurrent-8            3683365               326 ns/op               0 B/op          0 allocs/op
BenchmarkCommonsPool-8                    1828080               669 ns/op             103 B/op          3 allocs/op
BenchmarkCommonsPoolWithConcurrent-8      1715344               703 ns/op              32 B/op          1 allocs/op

Documentation

Index

• Constants
• Variables
• type Config
  • func NewConfig(objectCreateFactory ObjectCreateFactory) Config
  • func NewDefaultConfig() Config
• type ObjectCreateFactory
• type ObjectDestroyFactory
• type ObjectValidateFactory
• type Pool
  • func New(config Config) (*Pool, error)
  • func (p *Pool) ActiveSize() int
  • func (p *Pool) BorrowObject(ctx context.Context) (interface{}, error)
  • func (p *Pool) Close(ctx context.Context) error
  • func (p *Pool) Evict(ctx context.Context) error
  • func (p *Pool) IdleSize() int
  • func (p *Pool) InvalidateObject(ctx context.Context, object interface{}) error
  • func (p *Pool) ReturnObject(ctx context.Context, object interface{}) error
  • func (p *Pool) Size() int
  • func (p *Pool) StartEvictor()

Constants

const (
	DefaultMaxSize             = 10
	DefaultMinIdle             = 0
	DefaultMaxIdle             = 10
	DefaultMinIdleTime         = time.Minute * 5
	DefaultNonblocking         = false
	DefaultAutoEvict           = true
	DefaultEvictInterval       = time.Second * 30
	DefaultMaxValidateAttempts = 1
)

Variables

var (
	DefaultObjectValidateFactory ObjectValidateFactory = func(ctx context.Context, object interface{}) bool {
		return true
	}
	DefaultObjectDestroyFactory ObjectDestroyFactory = func(ctx context.Context, object interface{}) error {
		return nil
	}
)

var (
	ErrPoolClosed                  = errors.New("pool has been closed")
	ErrPoolFulled                  = errors.New("pool is full")
	ErrPoolExhausted               = errors.New("pool is exhausted")
	ErrObjectNotFound              = errors.New("object not found")
	ErrObjectValidateFailed        = errors.New("object validate failed")
	ErrObjectCreateFactoryNotFound = errors.New("the factory of object creating not found")
)

Types

type Config

type Config struct {
	/**
	The capacity of the pool. If MaxSize <= 0, no capacity limit.
	*/
	MaxSize int
	/**
	The minimum size of the idle objects.
	*/
	MinIdle int
	/**
	The maximal size of the idle objects. Idle objects exceeding MaxIdle will be evicted.
	*/
	MaxIdle int
	/**
	The minimum time that idle object should be reserved.
	*/
	MinIdleTime time.Duration
	/**
	The blocking policy. If true, it will return ErrPoolExhausted when pool is exhausted.
	*/
	Nonblocking bool
	/**
	Enable auto evict idle objects. When true, pool will create a goroutine to start a evictor.
	*/
	AutoEvict bool
	/**
	The interval between evict.
	*/
	EvictInterval time.Duration
	/**
	The maximal attempts to validate object.
	*/
	MaxValidateAttempts int
	/**
	The factory of creating object.
	*/
	ObjectCreateFactory ObjectCreateFactory
	/**
	The factory of validating object.
	*/
	ObjectValidateFactory ObjectValidateFactory
	/**
	The factory of destroying object.
	*/
	ObjectDestroyFactory ObjectDestroyFactory
}

func NewConfig

func NewConfig(objectCreateFactory ObjectCreateFactory) Config

func NewDefaultConfig

func NewDefaultConfig() Config

type ObjectCreateFactory

type ObjectCreateFactory func(ctx context.Context) (interface{}, error)

type ObjectDestroyFactory

type ObjectDestroyFactory func(ctx context.Context, object interface{}) error

type ObjectValidateFactory

type ObjectValidateFactory func(ctx context.Context, object interface{}) bool

type Pool

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

Pool is a thread-safe pool

func New

func New(config Config) (*Pool, error)

New create a pool by config

func (*Pool) ActiveSize

func (p *Pool) ActiveSize() int

func (*Pool) BorrowObject

func (p *Pool) BorrowObject(ctx context.Context) (interface{}, error)

BorrowObject promise to return a idle object. It will be blocked when there is no any idle object.

func (*Pool) Close

func (p *Pool) Close(ctx context.Context) error

func (*Pool) Evict

func (p *Pool) Evict(ctx context.Context) error

func (*Pool) IdleSize

func (p *Pool) IdleSize() int

func (*Pool) InvalidateObject

func (p *Pool) InvalidateObject(ctx context.Context, object interface{}) error

InvalidateObject delete and destroy the active object

func (*Pool) ReturnObject

func (p *Pool) ReturnObject(ctx context.Context, object interface{}) error

func (*Pool) Size

func (p *Pool) Size() int

func (*Pool) StartEvictor

func (p *Pool) StartEvictor()