Skip to content
jackcPublic

About

Generic resource pool for Go

Topics

Resources

Stars

430 stars

Watchers

9 watching

Forks

Repository files navigation

Go Reference Build Status

Puddle

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 required for a resource pool. It can be used directly or it can be used as the base for a domain specific resource pool. 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.

Features

  • Acquire cancellation via context standard library
  • Statistics API for monitoring pool pressure
  • No dependencies outside of standard library and golang.org/x/sync
  • High performance
  • 100% test coverage of reachable code

Example Usage

package main

import (
	"context"
	"log"
	"net"

	"github.com/jackc/puddle/v2"
)

func main() {
	constructor := func(context.Context) (net.Conn, error) {
		return net.Dial("tcp", "127.0.0.1:8080")
	}
	destructor := func(value net.Conn) {
		value.Close()
	}
	maxPoolSize := int32(10)

	pool, err := puddle.NewPool(&puddle.Config[net.Conn]{Constructor: constructor, Destructor: destructor, MaxSize: maxPoolSize})
	if err != nil {
		log.Fatal(err)
	}

	// Acquire resource from the pool.
	res, err := pool.Acquire(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	// Use resource.
	_, err = res.Value().Write([]byte{1})
	if err != nil {
		log.Fatal(err)
	}

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

Status

Puddle is stable and feature complete.

  • Bug reports and fixes are welcome.
  • New features will usually not be accepted if they can be feasibly implemented in a wrapper.
  • Performance optimizations will usually not be accepted unless the performance issue rises to the level of a bug.

The lifecycle contract documents ownership, cancellation, reset, and shutdown guarantees. The bounded TLA+ model checks those guarantees alongside the race-enabled Go tests in CI.

Supported Go Versions

puddle supports the same versions of Go that are supported by the Go project: the two most recent major releases. The minimum Go version is 1.26.11. CI tests this minimum alongside the latest patches of the two supported releases.

Differences with Go sync.Pool

They are intended for entirely different types of resources:

  • sync.Pool would generally be used for in memory objects.
  • Puddle would generally be used for handles to external objects such as connections, file handles, etc.

Specific differences:

  • sync.Pool does not have a way to limit max resources in pool.
  • sync.Pool does not have a way to ensure at least min resources in pool.
  • sync.Pool can drop resources in pool at any time - not ideal for expensive to create connections.
  • sync.Pool does not have a cleanup / release function. Resources are GCed without a chance to close cleanly.
  • sync.Pool does not have a way to handle errors creating the resource
  • sync.Pool does not support context to limit time to wait creating a resource

License

MIT

About

Generic resource pool for Go

Topics

Resources

Stars

430 stars

Watchers

9 watching

Forks

Releases

Packages

Used by

Contributors

Languages