pool

README

A resource sensitive pool for Golang

go get github.com/damnever/pool

👉 Example

👉 Doc

Documentation

Overview

Package pool manage reuseable resources like 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 (p *Pool) Close() error
  • func (p *Pool) Get(ctx context.Context) (Resource, error)
  • func (p *Pool) GetNoWait() (Resource, error)
  • func (p *Pool) Put(r Resource) error
• 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")
	// ErrNoMatch indicates no Get/GetNoWait matched in previous call,
	// you will never see this error unless you do some thing wrong,
	// it will panic :-)
	ErrNoMatch = errors.New("no Get/GetNoWait matched")
)

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.
	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
}

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 (*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) 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 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.