puddle – github.com/jackc/puddle Index | Examples | Files

package puddle

import "github.com/jackc/puddle"

Package puddle is a generic resource pool.

Puddle is a tiny generic resource pool library for Go that uses the standard context library to signal cancellation of acquires. It is designed to contain the minimum functionality a resource pool needs that cannot be implemented without concurrency concerns. For example, a database connection pool may use puddle internally and implement health checks and keep-alive behavior without needing to implement any concurrent code of its own.

Index

Examples

Variables 

var ErrClosedPool = errors.New("closed pool")

ErrClosedPool occurs on an attempt to acquire a connection from a closed pool or a pool that is closed while the acquire is waiting.

Types

type Constructor 

type Constructor func(ctx context.Context) (res interface{}, err error)

Constructor is a function called by the pool to construct a resource.

type Destructor 

type Destructor func(res interface{})

Destructor is a function called by the pool to destroy a resource.

type Pool 

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

Pool is a concurrency-safe resource pool.

Example

Code:play  

package main

import (
	"context"
	"fmt"
	"log"
	"net"

	"github.com/jackc/puddle"
)

func startAcceptOnceDummyServer(laddr string) {
	ln, err := net.Listen("tcp", laddr)
	if err != nil {
		log.Fatalln("Listen:", err)
	}

	go func() {
		conn, err := ln.Accept()
		if err != nil {
			log.Fatalln("Accept:", err)
		}

		for {
			buf := make([]byte, 1)
			_, err := conn.Read(buf)
			if err != nil {
				return
			}
		}
	}()

}

func main() {
	// Dummy server
	laddr := "127.0.0.1:8080"
	startAcceptOnceDummyServer(laddr)

	// Pool creation
	constructor := func(context.Context) (interface{}, error) {
		return net.Dial("tcp", laddr)
	}
	destructor := func(value interface{}) {
		value.(net.Conn).Close()
	}
	maxPoolSize := int32(10)

	pool := puddle.NewPool(constructor, destructor, maxPoolSize)

	// Use pool multiple times
	for i := 0; i < 10; i++ {
		// Acquire resource
		res, err := pool.Acquire(context.Background())
		if err != nil {
			log.Fatalln("Acquire", err)
		}

		// Type-assert value and use
		_, err = res.Value().(net.Conn).Write([]byte{1})
		if err != nil {
			log.Fatalln("Write", err)
		}

		// Release when done.
		res.Release()
	}

	stats := pool.Stat()
	pool.Close()

	fmt.Println("Connections:", stats.TotalResources())
	fmt.Println("Acquires:", stats.AcquireCount())
}

Output:

Connections: 1
Acquires: 10

func NewPool 

func NewPool(constructor Constructor, destructor Destructor, maxSize int32) *Pool

NewPool creates a new pool. Panics if maxSize is less than 1.

func (*Pool) Acquire 

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

Acquire gets a resource from the pool. If no resources are available and the pool is not at maximum capacity it will create a new resource. If the pool is at maximum capacity it will block until a resource is available. ctx can be used to cancel the Acquire.

func (*Pool) AcquireAllIdle 

func (p *Pool) AcquireAllIdle() []*Resource

AcquireAllIdle atomically acquires all currently idle resources. Its intended use is for health check and keep-alive functionality. It does not update pool statistics.

func (*Pool) Close 

func (p *Pool) Close()

Close destroys all resources in the pool and rejects future Acquire calls. Blocks until all resources are returned to pool and destroyed.

func (*Pool) Stat 

func (p *Pool) Stat() *Stat

Stat returns the current pool statistics.

type Resource 

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

Resource is the resource handle returned by acquiring from the pool.

func (*Resource) CreationTime 

func (res *Resource) CreationTime() time.Time

CreationTime returns when the resource was created by the pool.

func (*Resource) Destroy 

func (res *Resource) Destroy()

Destroy returns the resource to the pool for destruction. res must not be subsequently used.

func (*Resource) Hijack 

func (res *Resource) Hijack()

Hijack assumes ownership of the resource from the pool. Caller is responsible for cleanup of resource value.

func (*Resource) Release 

func (res *Resource) Release()

Release returns the resource to the pool. res must not be subsequently used.

func (*Resource) Value 

func (res *Resource) Value() interface{}

Value returns the resource value.

type Stat 

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

Stat is a snapshot of Pool statistics.

func (*Stat) AcquireCount 

func (s *Stat) AcquireCount() int64

AcquireCount returns the number of successful acquires from the pool.

func (*Stat) AcquireDuration 

func (s *Stat) AcquireDuration() time.Duration

AcquireDuration returns the total duration of all successful acquires from the pool.

func (*Stat) AcquiredResources 

func (s *Stat) AcquiredResources() int32

AcquiredResources returns the number of acquired resources in the pool.

func (*Stat) CanceledAcquireCount 

func (s *Stat) CanceledAcquireCount() int64

CanceledAcquireCount returns the number of acquires from the pool that were canceled by a context.

func (*Stat) ConstructingResources 

func (s *Stat) ConstructingResources() int32

ConstructingResources returns the number of resources with construction in progress in the pool.

func (*Stat) EmptyAcquireCount 

func (s *Stat) EmptyAcquireCount() int64

EmptyAcquireCount returns the number of successful acquires from the pool that waited for a resource to be released or constructed because the pool was empty.

func (*Stat) IdleResources 

func (s *Stat) IdleResources() int32

IdleResources returns the number of idle resources in the pool.

func (*Stat) MaxResources 

func (s *Stat) MaxResources() int32

MaxResources returns the maximum size of the pool.

func (*Stat) TotalResources 

func (s *Stat) TotalResources() int32

TotalResource returns the total number of resources.

Source Files

doc.go pool.go

Version
v1.0.0
Published
Jun 8, 2019
Platform
darwin/amd64
Imports
4 packages
Last checked
now –

Tools for package owners.