whatcanGOwrong

go/pkg/mod/github.com/jackc/puddle@v1.3.0/README.md

@@ -0,0 +1,62 @@
+[![](https://godoc.org/github.com/jackc/puddle?status.svg)](https://godoc.org/github.com/jackc/puddle)
+![Build Status](https://github.com/jackc/puddle/actions/workflows/ci.yml/badge.svg)
+
+# 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
+* High performance
+* 100% test coverage
+
+## Example Usage
+
+```go
+constructor := func(context.Context) (interface{}, error) {
+  return net.Dial("tcp", "127.0.0.1:8080")
+}
+destructor := func(value interface{}) {
+  value.(net.Conn).Close()
+}
+maxPoolSize := 10
+
+pool := puddle.NewPool(constructor, destructor, maxPoolSize)
+
+// Acquire resource from the pool.
+res, err := pool.Acquire(context.Background())
+if err != nil {
+  // ...
+}
+
+// Use resource.
+_, err = res.Value().(net.Conn).Write([]byte{1})
+if err != nil {
+  // ...
+}
+
+// Release when done.
+res.Release()
+
+```
+
+## Status
+
+Puddle v1 is complete. No changes are planned.
+
+* Bug reports and fixes are welcome.
+* New features will not be accepted if they can be feasibly implemented in a wrapper.
+* Performance optimizations will not be accepted unless the performance issue rises to the level of a bug.
+
+## License
+
+MIT