Merge pull request #4 from FishGoddess/develop

v0.2.2

Author: FishGoddess

.github/workflows/test.yml

@@ -7,12 +7,16 @@ on:
 
 jobs:
   test-project:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
+      - run: uname -a
+      - run: lsb_release -a
+
       - name: Setup
         uses: actions/setup-go@v4
         with:
           go-version: "1.23"
+
       - run: go version
 
       - name: Checkout

FUTURE.md

@@ -1,9 +1,15 @@
-## ✈️ 未来版本的新特性 (Features in future versions)
+## ✈️ 未来版本的新特性
+
+### v0.3.x
+
+* [ ] 增加生命周期检测，资源检查回调
 
 ### v0.2.x
 
 * [x] 优化代码
-* [ ] 增加生命周期检测，资源检查回调
+* [x] Acquire 函数支持 context 的透传
+* [x] Release 函数支持 context 的透传
+* [x] 调整错误类型，调整错误处理选项函数
 
 ### v0.1.x
 

HISTORY.md

@@ -1,4 +1,12 @@
-## 📜 历史版本的特性介绍 (Features in old versions)
+## 📜 历史版本的特性介绍
+
+### v0.2.2
+
+> 此版本发布于 2025-04-29
+
+* Acquire 函数支持 context 的透传
+* Release 函数支持 context 的透传
+* 调整错误类型，调整错误处理选项函数
 
 ### v0.2.1
 

README.en.md

@@ -5,13 +5,16 @@
 [![Coverage](_icons/coverage.svg)](_icons/coverage.svg)
 ![Test](https://github.com/FishGoddess/rego/actions/workflows/test.yml/badge.svg)
 
-**Rego** is a resource pool library which is used for controlling and reusing some resources like network connection.
+**Rego** is a resource pool used for reusing some resources like network connections.
 
 [阅读中文版的文档](./README.md)
 
 ### 🍭 Features
 
-* Based resource pool, which can limit the count of resources.
+* Reuse resources by limiting the quantity of resources
+* Error handling callback for different errors
+* Check pool status like acquired and idle quantity
+* Passing context to callbacks
 
 _Check [HISTORY.md](./HISTORY.md) and [FUTURE.md](./FUTURE.md) to know about more information._
 
@@ -33,31 +36,34 @@ import (
 )
 
 // acquireConn acquires a new conn, and returns an error if failed.
-func acquireConn() (net.Conn, error) {
+func acquireConn(ctx context.Context) (net.Conn, error) {
 	// Guess this ip is from which websites?
-	return net.Dial("tcp", "20.205.243.166:80")
+	var dialer net.Dialer
+	return dialer.DialContext(ctx, "tcp", "20.205.243.166:80")
 }
 
 // releaseConn releases the given conn, and returns an error if failed.
-func releaseConn(conn net.Conn) error {
+func releaseConn(ctx context.Context, conn net.Conn) error {
 	return conn.Close()
 }
 
 func main() {
 	// Create a resource pool which type is net.Conn and limit is 64.
+	ctx := context.Background()
+
 	pool := rego.New(64, acquireConn, releaseConn)
-	defer pool.Close()
+	defer pool.Close(ctx)
 
 	// Take a resource from pool.
-	conn, err := pool.Take(context.Background())
+	conn, err := pool.Take(ctx)
 	if err != nil {
 		panic(err)
 	}
 
 	// Remember put the client to pool when your using is done.
 	// This is why we call the resource in pool is reusable.
 	// We recommend you to do this job in a defer function.
-	defer pool.Put(conn)
+	defer pool.Put(ctx, conn)
 
 	// Use the conn
 	fmt.Println(conn.RemoteAddr())

README.md

@@ -5,13 +5,16 @@
 [![Coverage](_icons/coverage.svg)](_icons/coverage.svg)
 ![Test](https://github.com/FishGoddess/rego/actions/workflows/test.yml/badge.svg)
 
-**Rego** 是一个简单的资源池库，用于控制、复用一些特定的资源，比如说网络连接。
+**Rego** 是一个简单的资源池库，用于复用一些特定的资源，比如说网络连接。
 
 [Read me in English](./README.en.md)
 
 ### 🍭 功能特性
 
-* 简单的资源池，可以控制资源数量
+* 简单复用资源，支持限制数量
+* 支持错误处理回调，用于自定义业务方的特定错误
+* 支持查询资源池的运行情况，比如已获取和空闲的资源数量
+* 回调函数支持 context 的透传
 
 _历史版本的特性请查看 [HISTORY.md](./HISTORY.md)。未来版本的新特性和计划请查看 [FUTURE.md](./FUTURE.md)。_
 
@@ -33,31 +36,34 @@ import (
 )
 
 // acquireConn acquires a new conn, and returns an error if failed.
-func acquireConn() (net.Conn, error) {
+func acquireConn(ctx context.Context) (net.Conn, error) {
 	// Guess this ip is from which websites?
-	return net.Dial("tcp", "20.205.243.166:80")
+	var dialer net.Dialer
+	return dialer.DialContext(ctx, "tcp", "20.205.243.166:80")
 }
 
 // releaseConn releases the given conn, and returns an error if failed.
-func releaseConn(conn net.Conn) error {
+func releaseConn(ctx context.Context, conn net.Conn) error {
 	return conn.Close()
 }
 
 func main() {
 	// Create a resource pool which type is net.Conn and limit is 64.
+	ctx := context.Background()
+
 	pool := rego.New(64, acquireConn, releaseConn)
-	defer pool.Close()
+	defer pool.Close(ctx)
 
 	// Take a resource from pool.
-	conn, err := pool.Take(context.Background())
+	conn, err := pool.Take(ctx)
 	if err != nil {
 		panic(err)
 	}
 
 	// Remember put the client to pool when your using is done.
 	// This is why we call the resource in pool is reusable.
 	// We recommend you to do this job in a defer function.
-	defer pool.Put(conn)
+	defer pool.Put(ctx, conn)
 
 	// Use the conn
 	fmt.Println(conn.RemoteAddr())

_examples/basic.go

@@ -13,31 +13,34 @@ import (
 )
 
 // acquireConn acquires a new conn, and returns an error if failed.
-func acquireConn() (net.Conn, error) {
+func acquireConn(ctx context.Context) (net.Conn, error) {
 	// Guess this ip is from which websites?
-	return net.Dial("tcp", "20.205.243.166:80")
+	var dialer net.Dialer
+	return dialer.DialContext(ctx, "tcp", "20.205.243.166:80")
 }
 
 // releaseConn releases the given conn, and returns an error if failed.
-func releaseConn(conn net.Conn) error {
+func releaseConn(ctx context.Context, conn net.Conn) error {
 	return conn.Close()
 }
 
 func main() {
 	// Create a resource pool which type is net.Conn and limit is 64.
+	ctx := context.Background()
+
 	pool := rego.New(64, acquireConn, releaseConn)
-	defer pool.Close()
+	defer pool.Close(ctx)
 
 	// Take a resource from pool.
-	conn, err := pool.Take(context.Background())
+	conn, err := pool.Take(ctx)
 	if err != nil {
 		panic(err)
 	}
 
 	// Remember put the client to pool when your using is done.
 	// This is why we call the resource in pool is reusable.
 	// We recommend you to do this job in a defer function.
-	defer pool.Put(conn)
+	defer pool.Put(ctx, conn)
 
 	// Use the conn
 	fmt.Println(conn.RemoteAddr())

_examples/errors.go

@@ -13,24 +13,24 @@ import (
 )
 
 var (
-	errPoolIsFull   = errors.New("_examples: pool is full")
-	errPoolIsClosed = errors.New("_examples: pool is closed")
+	errPoolExhausted = errors.New("_examples: pool is exhausted")
+	errPoolClosed    = errors.New("_examples: pool is closed")
 )
 
-func acquire() (int, error) {
+func acquire(ctx context.Context) (int, error) {
 	return 0, nil
 }
 
-func release(resource int) error {
+func release(ctx context.Context, resource int) error {
 	return nil
 }
 
-func newPoolFullErr(ctx context.Context) error {
-	return errPoolIsFull
+func newPoolExhaustedErr(ctx context.Context) error {
+	return errPoolExhausted
 }
 
 func newPoolClosedErr(ctx context.Context) error {
-	return errPoolIsClosed
+	return errPoolClosed
 }
 
 func main() {
@@ -42,36 +42,36 @@ func main() {
 	resource, err := pool.Take(ctx)
 	fmt.Println(resource, err)
 
-	// However, the pool is full after taking one resource without putting.
-	// It will return a full error.
+	// However, the pool is exhausted after taking one resource without putting.
+	// It will return an exhausted error.
 	resource, err = pool.Take(ctx)
-	fmt.Println(resource, err, err == rego.ErrPoolIsFull)
+	fmt.Println(resource, err, err == rego.ErrPoolExhausted)
 
 	// Put the resource back to the pool.
-	pool.Put(resource)
-	pool.Close()
+	pool.Put(ctx, resource)
+	pool.Close(ctx)
 
 	// Now, the pool is closed so any taking from the pool will return a closed error.
 	resource, err = pool.Take(ctx)
-	fmt.Println(resource, err, err == rego.ErrPoolIsClosed)
+	fmt.Println(resource, err, err == rego.ErrPoolClosed)
 
 	// Create a pool with limit and fast-failed and new error funcs.
-	pool = rego.New(1, acquire, release, rego.WithFastFailed(), rego.WithPoolFullErr(newPoolFullErr), rego.WithPoolClosedErr(newPoolClosedErr))
+	pool = rego.New(1, acquire, release, rego.WithFastFailed(), rego.WithPoolExhaustedErr(newPoolExhaustedErr), rego.WithPoolClosedErr(newPoolClosedErr))
 
 	// Take one resource from pool which is ok.
 	resource, err = pool.Take(ctx)
 	fmt.Println(resource, err)
 
-	// However, the pool is full after taking one resource without putting.
-	// It will return a customizing full error.
+	// However, the pool is exhausted after taking one resource without putting.
+	// It will return a customizing exhausted error.
 	resource, err = pool.Take(ctx)
-	fmt.Println(resource, err, err == errPoolIsFull)
+	fmt.Println(resource, err, err == errPoolExhausted)
 
 	// Put the resource back to the pool.
-	pool.Put(resource)
-	pool.Close()
+	pool.Put(ctx, resource)
+	pool.Close(ctx)
 
 	// Now, the pool is closed so any taking from the pool will return a customizing closed error.
 	resource, err = pool.Take(ctx)
-	fmt.Println(resource, err, err == errPoolIsClosed)
+	fmt.Println(resource, err, err == errPoolClosed)
 }

_examples/pool.go

@@ -26,6 +26,7 @@ func runServer() {
 		}
 
 		fmt.Println("server:", string(bs))
+		time.Sleep(time.Second)
 	})
 
 	if err := http.ListenAndServe("127.0.0.1:9876", nil); err != nil {
@@ -34,20 +35,21 @@ func runServer() {
 }
 
 // acquireClient acquires a new http client, and returns an error if failed.
-func acquireClient() (*http.Client, error) {
+func acquireClient(ctx context.Context) (*http.Client, error) {
 	fmt.Println("acquire client...")
 	return &http.Client{}, nil
 }
 
 // releaseClient releases the given client, and returns an error if failed.
-func releaseClient(client *http.Client) error {
+func releaseClient(ctx context.Context, client *http.Client) error {
 	fmt.Println("release client...")
 	return nil
 }
 
 func main() {
 	// Prepare some backend resources.
 	ctx := context.Background()
+
 	go runServer()
 	time.Sleep(time.Second)
 
@@ -57,7 +59,7 @@ func main() {
 	// The release function is for releasing the given resource, and you can destroy everything of your resource.
 	// Also, you can specify some options to change the default settings.
 	pool := rego.New(4, acquireClient, releaseClient)
-	defer pool.Close()
+	defer pool.Close(ctx)
 
 	var wg sync.WaitGroup
 	for i := 0; i < 20; i++ {
@@ -75,10 +77,11 @@ func main() {
 			// Remember put the client to pool when your using is done.
 			// This is why we call the resource in pool is reusable.
 			// We recommend you to do this job in a defer function.
-			defer pool.Put(client)
+			defer pool.Put(ctx, client)
 
 			// Use the client whatever you want.
 			body := strings.NewReader(strconv.Itoa(ii))
+
 			_, err = client.Post("http://127.0.0.1:9876", "", body)
 			if err != nil {
 				panic(err)
@@ -87,5 +90,4 @@ func main() {
 	}
 
 	wg.Wait()
-	time.Sleep(time.Second)
 }