github.com/andoma-go/puddle/v2@v2.2.1/README.md (about)

     1  [![](https://godoc.org/github.com/andoma-go/puddle?status.svg)](https://godoc.org/github.com/andoma-go/puddle)
     2  ![Build Status](https://github.com/andoma-go/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/andoma-go/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