# bounded-threadpool

**Repository Path**: mtrdong/bounded-threadpool

## Basic Information

- **Project Name**: bounded-threadpool
- **Description**: 基于标准库 concurrent.futures.ThreadPoolExecutor 扩展的有界线程池执行器
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-30
- **Last Updated**: 2025-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Bounded ThreadPool Executor

[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个基于标准库`ThreadPoolExecutor`扩展的**有界线程池执行器**。

## 特性

- 🚀 **有界任务队列**：防止无限制的内存增长
- 🔧 **多种拒绝策略**：支持中止、丢弃、调用者运行等策略
- 🛡️ **线程安全**：完整的线程安全保证
- 📈 **动态线程调整**：根据需要自动创建和回收线程
- 💡 **Future 支持**：与 `concurrent.futures.Future` 完全兼容

## 安装

```bash
pip install bounded-threadpool
```

或者从源码安装：

```bash
git clone https://gitee.com/mtrdong/bounded-threadpool.git
cd bounded-threadpool
pip install -e .
```

## 快速开始

### 基本用法

```python
from bounded_threadpool import BoundedThreadPoolExecutor

def task(n):
    return n * n

with BoundedThreadPoolExecutor(max_workers=1, max_queue_size=1) as executor:
    future = executor.submit(task, 9)
    result = future.result()
    print(f"任务结果: {result}")  # 输出: 任务结果: 81
```

### 使用拒绝策略

```python
from bounded_threadpool import BoundedThreadPoolExecutor, AbortPolicy, DiscardPolicy, CallerRunsPolicy

# 中止策略（默认）：队列满时抛出异常
executor = BoundedThreadPoolExecutor(
    max_workers=1,
    max_queue_size=1,
    rejection_handler=AbortPolicy()
)

# 丢弃策略：队列满时静默丢弃任务
executor = BoundedThreadPoolExecutor(
    max_workers=1,
    max_queue_size=1,
    rejection_handler=DiscardPolicy()
)

# 调用者运行策略：队列满时在调用线程中执行
executor = BoundedThreadPoolExecutor(
    max_workers=1,
    max_queue_size=1,
    rejection_handler=CallerRunsPolicy()
)
```

### 线程初始化

```python
from bounded_threadpool import BoundedThreadPoolExecutor


def init_worker():
    print('工作线程已初始化')


with BoundedThreadPoolExecutor(
    max_workers=1,
    max_queue_size=1,
    initializer=init_worker,
    initargs=()
) as executor:
    # 工作线程会调用 init_worker 进行初始化
    pass
```

## 拒绝策略

| 策略                           | 行为                                      |
|------------------------------|-----------------------------------------|
| 中止策略：`AbortPolicy()`         | 当任务队列已满时，抛出 `RejectedExecutionError` 异常 |
| 丢弃策略：`DiscardPolicy()`       | 当任务队列已满时，静默丢弃新提交的任务，并取消对应的 Future       |
| 调用者运行策略：`CallerRunsPolicy()` | 当任务队列已满时，在提交任务的线程中直接执行任务                |

## API 参考

### BoundedThreadPoolExecutor

```python
BoundedThreadPoolExecutor(
    max_workers: Optional[int] = None,
    thread_name_prefix: Optional[str] = None,
    initializer: Optional[Callable] = None,
    initargs: tuple = (),
    max_queue_size: Optional[int] = None,
    rejection_handler: Optional['RejectedExecutionHandler'] = None
)
```

**参数**：

- `max_workers`: 最大工作线程数（默认：CPU核心数+4，最大32）
- `thread_name_prefix`: 工作线程名称前缀
- `initializer`: 线程初始化函数
- `initargs`: 初始化函数参数
- `max_queue_size`: 任务队列最大容量（默认：无限制）
- `rejection_handler`: 拒绝策略处理器（默认：AbortPolicy）

**方法**：

- `submit(fn, /, *args, **kwargs)`: 提交任务到线程池
- `shutdown(wait=True, *, cancel_futures=False)`: 关闭线程池

## 许可证

MIT License

## 致谢

本项目基于 Python 标准库 `concurrent.futures.ThreadPoolExecutor` 进行扩展，增加了有界队列和拒绝策略支持。