github.com/jackc/puddle/v2@v2.2.2-0.20240301145809-72b022bcfc59/README.md (about) 1 [![Go Reference](https://pkg.go.dev/badge/github.com/jackc/puddle/v2.svg)](https://pkg.go.dev/github.com/jackc/puddle/v2) 2 ![Build Status](https://github.com/jackc/puddle/actions/workflows/ci.yml/badge.svg) 3 4 # Puddle 5 6 Puddle is a tiny generic resource pool library for Go that uses the standard 7 context library to signal cancellation of acquires. It is designed to contain 8 the minimum functionality required for a resource pool. It can be used directly 9 or it can be used as the base for a domain specific resource pool. For example, 10 a database connection pool may use puddle internally and implement health checks 11 and keep-alive behavior without needing to implement any concurrent code of its 12 own. 13 14 ## Features 15 16 * Acquire cancellation via context standard library 17 * Statistics API for monitoring pool pressure 18 * No dependencies outside of standard library and golang.org/x/sync 19 * High performance 20 * 100% test coverage of reachable code 21 22 ## Example Usage 23 24 ```go 25 package main 26 27 import ( 28 "context" 29 "log" 30 "net" 31 32 "github.com/jackc/puddle/v2" 33 ) 34 35 func main() { 36 constructor := func(context.Context) (net.Conn, error) { 37 return net.Dial("tcp", "127.0.0.1:8080") 38 } 39 destructor := func(value net.Conn) { 40 value.Close() 41 } 42 maxPoolSize := int32(10) 43 44 pool, err := puddle.NewPool(&puddle.Config[net.Conn]{Constructor: constructor, Destructor: destructor, MaxSize: maxPoolSize}) 45 if err != nil { 46 log.Fatal(err) 47 } 48 49 // Acquire resource from the pool. 50 res, err := pool.Acquire(context.Background()) 51 if err != nil { 52 log.Fatal(err) 53 } 54 55 // Use resource. 56 _, err = res.Value().Write([]byte{1}) 57 if err != nil { 58 log.Fatal(err) 59 } 60 61 // Release when done. 62 res.Release() 63 } 64 ``` 65 66 ## Status 67 68 Puddle is stable and feature complete. 69 70 * Bug reports and fixes are welcome. 71 * New features will usually not be accepted if they can be feasibly implemented in a wrapper. 72 * Performance optimizations will usually not be accepted unless the performance issue rises to the level of a bug. 73 74 ## Supported Go Versions 75 76 puddle supports the same versions of Go that are supported by the Go project. For [Go](https://golang.org/doc/devel/release.html#policy) that is the two most recent major releases. This means puddle supports Go 1.19 and higher. 77 78 ## License 79 80 MIT