lifopool

README

LifoPool

High-Performance, Feature-Rich, and Production-Ready Goroutine Pool for Go.

English | 中文文档

---

🚀 Introduction

lifopool is a library designed to manage specific goroutine workers to handle tasks concurrently. It reuses goroutines to limit concurrency, reduce resource consumption, and improve the stability and performance of your applications.

Key differentiators:

• LIFO Scheduling: Improves CPU cache locality by prioritizing recently used workers.
• Dynamic Resizing: Automatically scales workers up or down based on traffic load.
• Robustness: Built-in panic recovery, timeout handling, and retry mechanisms.

📊 Benchmarks

lifopool is optimized for speed and efficiency. Below are benchmark results comparing it with other popular libraries (ants, pond) and raw goroutines.

Library	Optimization	Time (ns/op)	Memory (B/op)	Allocations (allocs/op)
lifopool	Default	1,114,703,667	2,757,944	14,906
ants	-	1,141,786,333	4,533,200	59,463
pond	-	1,479,714,792	1,035,432	10,788
Raw Goroutines	None	336,763,680	128,759,930	3,007,120

Highlights:

• Faster than ants and pond in handling 1 million tasks.
• 50% Less Memory usage compared to ants.
• Significant reduction in allocations compared to raw goroutines and ants.

Benchmarks run on Apple M3, processing 1M tasks.

✨ Features

• 🚀 High Performance: Low overhead, LIFO stack-based worker management.
• ⚖️ Dynamic Scaling: Auto-scale worker count based on queue monitoring.
• 🛡️ Panic Recovery: Automatically recovers from worker panics to prevent leaks.
• ⏱️ Timeout Support: Task execution timeouts with context integration.
• 🔄 Retry Mechanism: Configurable retries for failed tasks.
• 🔒 Custom Lock: Standard sync.Mutex or high-performance SpinLock support.

📦 Installation

go get -u github.com/morsuning/lifopool

⚡ Quick Start

Simple Usage

package main

import (
    "fmt"
    "time"
    "github.com/morsuning/lifopool"
)

func main() {
    pool := lifopool.New(100)
    defer pool.Release()

    pool.AddTask(func() (any, error) {
        time.Sleep(10 * time.Millisecond)
        fmt.Println("Hello, lifopool!")
        return nil, nil
    })
    
    pool.Wait()
}

See examples/ for more usage patterns, including Custom Locks and Timeout handling.

⚙️ Configuration

lifopool.New accepts functional options to tailor behavior:

Option	Description	Default
WithMinWorkers(n)	Minimum idle workers to keep.	maxWorkers
WithTaskQueueSize(n)	Size of the buffered task channel.	1e6
WithTimeout(d)	Execution timeout for tasks.	0 (None)
WithRetryCount(n)	Retries upon failure.	0
WithErrorCallback(fn)	Callback for task errors/panics.	nil
WithLock(l)	Custom lock implementation.	sync.Mutex

🤝 Contributing

Contributions are welcome! Please check out the issues or submit a PR.

📄 License

MIT © morsuning

Documentation

Index

• type Option
  • func WithErrorCallback(callback func(error)) Option
  • func WithLock(lock sync.Locker) Option
  • func WithMinWorkers(minWorkers int) Option
  • func WithResultCallback(callback func(any)) Option
  • func WithRetryCount(retryCount int) Option
  • func WithTaskQueueSize(size int) Option
  • func WithTimeout(timeout time.Duration) Option
• type Pool
  • func New(maxWorkers int, opts ...Option) Pool

Types

type Option

type Option func(*lifoPool)

Option 代表池的一个选项。

func WithErrorCallback

func WithErrorCallback(callback func(error)) Option

WithErrorCallback 设置池的错误回调。

func WithLock

func WithLock(lock sync.Locker) Option

WithLock 设置池的锁。

func WithMinWorkers

func WithMinWorkers(minWorkers int) Option

WithMinWorkers 设置池的最小工作者数量。

func WithResultCallback

func WithResultCallback(callback func(any)) Option

WithResultCallback 设置池的结果回调。

func WithRetryCount

func WithRetryCount(retryCount int) Option

WithRetryCount 设置池的重试次数。

func WithTaskQueueSize

func WithTaskQueueSize(size int) Option

WithTaskQueueSize 设置池的任务队列大小。

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout 设置池的超时时间。

type Pool

type Pool interface {
	// AddTask 向池中添加一个任务。
	AddTask(t task)
	// Wait 等待所有任务被分发并完成。
	Wait()
	// Release 释放池及其所有工作者。
	Release()
	// GetRunning 返回正在运行的工作者数量。
	Running() int
	// GetWorkerCount 返回工作者的总数量。
	GetWorkerCount() int
	// GetTaskQueueSize 返回任务队列的大小。
	GetTaskQueueSize() int
}

func New

func New(maxWorkers int, opts ...Option) Pool

NewGoPool 创建一个新的工作者池。