pool

Documentation

Overview

Package pool manages reuseable resources, such as connections.

Unlike other pool implementations, they fill the pool to full before reusing resources, this implementation only maintains possible minimal resources in the pool no matter how big the capacity is.

Example

package main

import (
	"fmt"
	"time"
)

type SomeResource struct {
	err error
}

func (r *SomeResource) Do() (res string, err error) {
	// if err = doSth(); err != nil {
	//   r.err = err // NOTE: Must record the error if error is not nil.
	//   return
	// }
	res = "hello"
	return
}

func (r *SomeResource) Err() error {
	return r.err
}

func (r *SomeResource) Close() error {
	return nil
}

func must(err error) {
	if err != nil {
		panic(err)
	}
}

func main() {
	pool, err := New(Options{
		ResourceFactory: func() (Resource, error) {
			return &SomeResource{}, nil
		},
		Capacity:    5,
		IdleTimeout: 30 * time.Second,
	})
	must(err)
	defer pool.Close()

	r, err := pool.GetNoWait()
	must(err)
	defer pool.Put(r)
	res, err := r.(*SomeResource).Do()
	must(err)
	fmt.Println(res)

}

Output:

hello

Index

• Variables
• type Options
• type Pool
  • func New(opts Options) (*Pool, error)
  • func NewWithCtx(ctx context.Context, opts Options) (*Pool, error)
  • func (p *Pool) Close() error
  • func (p *Pool) Get(ctx context.Context) (Resource, error)
  • func (p *Pool) GetNoWait() (Resource, error)
  • func (p *Pool) IdleNum() int
  • func (p *Pool) Put(r Resource) error
• type ResetableResource
• type Resource
• type TestableResource

Examples

• Package

Variables

var (
	// ErrPoolClosed indicates pool is closed.
	ErrPoolClosed = errors.New("pool closed")
	// ErrPoolIsBusy indicates no available resource in pool currently.
	ErrPoolIsBusy = errors.New("pool is busy")
	// ErrMismatch indicates no Get/GetNoWait matched in previous call,
	// you will never see this error unless you do some thing wrong,
	// it will panic :-)
	ErrMismatch = errors.New("no Get/GetNoWait matched in previous call")
)

Types

type Options

type Options struct {
	// ResourceFactory creates new resource.
	ResourceFactory func() (Resource, error)
	// Capacity sets the max pool size.
	Capacity int
	// IdleTimeout 0 indicate no idle timeout.
	// If TestWhileIdle is not set, the resource will be closed directly after timeout.
	IdleTimeout time.Duration
	// TestOnBorrow will test the resource before borrow and not idle for IdleTimeout,
	// the resource must implement the TestableResource interface.
	TestOnBorrow bool
	// TestWhileIdle will test the resource if resource idle for IdleTimeout before borrow,
	// if IdleTimeout less and equal than 0, this option is ignored.
	// the resource must implement the TestableResource interface.
	TestWhileIdle bool
	// ResetOnBorrow will reset the resource before borrow,
	// the resource must implement the ResetableResource interface.
	ResetOnBorrow bool
}

Options is used to configurate the Pool. Set TestOnBorrow(true), TestWhileIdle(true) and IdleTimeout(>0) together will always test the resource if resource is testable.

type Pool

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

Pool is the container for resources.

func New

func New(opts Options) (*Pool, error)

New creates a new Pool.

func NewWithCtx

func NewWithCtx(ctx context.Context, opts Options) (*Pool, error)

NewWithCtx creates a new Pool with given ctx.

func (*Pool) Close

func (p *Pool) Close() error

Close closes the pool and all idle resources in the pool.

func (*Pool) Get

func (p *Pool) Get(ctx context.Context) (Resource, error)

Get gets a resource from pool, block until resource available or context done.

func (*Pool) GetNoWait

func (p *Pool) GetNoWait() (Resource, error)

GetNoWait gets a resource from pool, return immediately.

func (*Pool) IdleNum

func (p *Pool) IdleNum() int

IdleNum returns the number of idle resources, it just a approximate figure.

func (*Pool) Put

func (p *Pool) Put(r Resource) error

Put puts back resource into pool, must record the error which can make resource unusable and let it returned by Err() so clean up work could be done properly. After pool close, Put is responsible for closing all in using resources.

type ResetableResource

type ResetableResource interface {
	Resource
	Reset() error
}

ResetableResource indicates the resource is resetable, Reset() will be called before every old resource return if ResetOnBorrow is set.

type Resource

type Resource interface {
	Err() error
	Close() error
}

Resource defines the interface that every resource must provide.

type TestableResource

type TestableResource interface {
	Resource
	Test() error
}

TestableResource indicates the resource is testable, Test() will be called before every old resource return if TestOnBorrow/TestWhileIdle is set.