github.com/panjf2000/ants/v2 使用教程

ants 是一个用于 Go 语言的高性能协程池库，它通过管理和复用协程来提高并发执行的效率，避免频繁创建和销毁协程带来的性能开销。以下是 ants 库的使用教程，包括基本使用和常见配置项的介绍。

1. 安装 ants 库

如果你使用的是 Go Modules，可以使用 go get 安装最新版：

go get -u github.com/panjf2000/ants/v2

2. 创建和使用协程池

创建一个基本的协程池

通过 ants.NewPool 函数创建一个协程池，指定最大容量来控制并发协程的数量。以下是一个简单的例子：

package main

import (
    "fmt"
    "github.com/panjf2000/ants/2"
    "time"
)

func main() {
    // 创建一个容量为10的协程池
    pool, _ := ants.NewPool(10)
    defer pool.Release() // 确保在结束时释放池

    // 向池中提交一个任务
    pool.Submit(func() {
        time.Sleep(2 * time.Second)
        fmt.Println("任务执行完成")
    })

    // 等待协程池中的任务完成
    time.Sleep(3 * time.Second)
}

3. 提交任务

使用 Submit 方法将任务提交到池中，任务可以是一个函数或其他任何符合类型要求的可执行对象。示例如下：

pool.Submit(func() {
    fmt.Println("任务正在执行")
})

4. 配置协程池

你可以通过 ants.Options 配置协程池的行为。常见的配置选项有：

• ExpiryDuration：指定每个工作协程的过期时间。超过这个时间未使用的协程会被销毁。
• PreAlloc：是否在初始化时预分配内存（对于高并发场景有性能提升作用）。
• MaxBlockingTasks：最大阻塞任务数，如果协程池满了，最大任务数限制会生效。
• Nonblocking：是否启用非阻塞模式。启用时，提交任务会立即返回，不会阻塞。
• PanicHandler：设置一个处理 panic 的函数，防止 panic 影响其他协程。

示例：使用配置选项创建协程池

package main

import (
    "fmt"
    "time"
    "github.com/panjf2000/ants/2"
)

func main() {
    // 设置协程池选项
    options := ants.Options{
        ExpiryDuration: 60 * time.Second, // 工作协程的过期时间
        PreAlloc:       true,             // 启用内存预分配
        Nonblocking:    true,             // 启用非阻塞模式
        PanicHandler: func(i interface{}) {
            fmt.Println("捕获到panic:", i)
        },
    }

    // 创建协程池
    pool, err := ants.NewPool(10, ants.WithOptions(options))
    if err != nil {
        panic(err)
    }
    defer pool.Release()

    // 提交任务
    pool.Submit(func() {
        fmt.Println("任务开始执行")
        panic("模拟panic错误")
    })

    // 等待一些时间以确保任务完成
    time.Sleep(2 * time.Second)
}

5. 动态调整池的容量

ants 支持在运行时动态调整池的容量，使用 Tune 方法来调整协程池的最大容量：

pool.Tune(20) // 调整池的容量为20

6. 协程池的其他功能

• Release：释放协程池中的所有资源。
• ReleaseTimeout：设置释放协程池时的超时时间。
  ReleaseTimeout 与 Release 类似，但具有超时，它会等待所有工作线程退出，然后再超时。
• Reboot：重启一个已释放的池，使其恢复使用。

示例：

// 释放协程池
pool.Release()

// 释放协程池并设置超时时间
pool.ReleaseTimeout(3 * time.Second)

// 重启已释放的池
pool.Reboot()

7. 处理 panic

ants 库的一个特性是，如果协程中的代码发生 panic，它会被 PanicHandler 捕获。你可以通过 PanicHandler 定制如何处理这些错误。例如，你可以记录日志或直接打印栈信息。

options := ants.Options{
    PanicHandler: func(i interface{}) {
        fmt.Println("捕获到panic:", i)
    },
}

8. 预分配内存

ants 提供了 WithPreAlloc 选项，可以在池初始化时预分配内存，这在处理大量任务时能够提高性能：

pool, _ := ants.NewPool(10000, ants.WithPreAlloc(true)) // 创建一个预分配内存的池

9. 常见问题

9.1. 池的容量已满怎么办？

• 默认情况下，如果池已满，提交任务时会被阻塞。你可以使用 Nonblocking 选项来避免阻塞，直接返回一个错误：

  pool, _ := ants.NewPool(10, ants.WithNonblocking(true))
  err := pool.Submit(func() {
      fmt.Println("任务执行")
  })
  if err != nil {
      fmt.Println("任务提交失败:", err)
  }

9.2. 如何清理过期的协程？

你可以通过 ExpiryDuration 设置协程的过期时间，池会定期清理空闲且超时的协程。示例：

options := ants.Options{
    ExpiryDuration: 30 * time.Second, // 设置协程过期时间为30秒
}

10. 总结

ants 是一个强大且灵活的协程池库，适用于高并发、高性能的应用场景。它提供了简便的 API 和多种配置选项，能够帮助开发者高效地管理和复用协程，提升程序的并发处理能力。

通过本教程，你可以了解如何创建协程池、提交任务、处理异常、调整池的容量以及优化内存使用等内容。如果你有更多性能需求，ants 提供的配置选项可以帮助你进一步优化协程池的行为。