Metadata-Version: 2.1
Name: betapool
Version: 1.0.1
Summary: Adaptive Thread Pool for GIL-Aware Concurrency Control in Python
Author: Mridankan Mandal
Maintainer: RedZapdos123
License: MIT
Project-URL: Homepage, https://github.com/RedZapdos123/BetaPool
Project-URL: Documentation, https://github.com/RedZapdos123/BetaPool#readme
Project-URL: Repository, https://github.com/RedZapdos123/BetaPool.git
Project-URL: Issues, https://github.com/RedZapdos123/BetaPool/issues
Project-URL: Changelog, https://github.com/RedZapdos123/BetaPool/blob/main/CHANGELOG.md
Project-URL: Paper, https://arxiv.org/abs/2601.10582
Keywords: concurrency,threading,thread-pool,gil,python,edge-computing,adaptive,scheduling,performance,optimization,blocking-ratio,beta-metric
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil<8.0.0,>=5.9.0
Provides-Extra: all
Requires-Dist: numpy<3.0.0,>=1.24.0; extra == "all"
Requires-Dist: matplotlib<4.0.0,>=3.7.0; extra == "all"
Requires-Dist: build<2.0.0,>=1.2.0; extra == "all"
Requires-Dist: twine<7.0.0,>=5.0.0; extra == "all"
Requires-Dist: pytest<9.0.0,>=7.3.0; extra == "all"
Requires-Dist: pytest-cov<7.0.0,>=4.0.0; extra == "all"
Requires-Dist: mypy<2.0.0,>=1.0.0; extra == "all"
Requires-Dist: black<25.0.0,>=23.0.0; extra == "all"
Requires-Dist: isort<6.0.0,>=5.12.0; extra == "all"
Requires-Dist: ruff<1.0.0,>=0.5.0; extra == "all"
Provides-Extra: dev
Requires-Dist: build<2.0.0,>=1.2.0; extra == "dev"
Requires-Dist: twine<7.0.0,>=5.0.0; extra == "dev"
Requires-Dist: pytest<9.0.0,>=7.3.0; extra == "dev"
Requires-Dist: pytest-cov<7.0.0,>=4.0.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.0.0; extra == "dev"
Requires-Dist: black<25.0.0,>=23.0.0; extra == "dev"
Requires-Dist: isort<6.0.0,>=5.12.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.5.0; extra == "dev"
Provides-Extra: numpy
Requires-Dist: numpy<3.0.0,>=1.24.0; extra == "numpy"
Provides-Extra: visualization
Requires-Dist: matplotlib<4.0.0,>=3.7.0; extra == "visualization"
Requires-Dist: numpy<3.0.0,>=1.24.0; extra == "visualization"

# BetaPool:

A Python library implementing the Metric-Driven Adaptive Thread Pool for mitigating GIL bottlenecks in mixed I/O and CPU workloads.

**Author:** Mridankan Mandal  
**License:** MIT  
**Python:** 3.8+

## Overview:

Standard thread pool implementations fail to detect GIL-specific contention in Python, leading to **concurrency thrashing** where increasing thread count paradoxically degrades throughput. BetaPool solves this by implementing a **GIL Safety Veto** mechanism using the **Blocking Ratio (beta)** metric to automatically maintain optimal concurrency levels.

## Why BetaPool:

Research demonstrates that naive thread scaling causes significant performance degradation:

| Configuration | Peak Throughput | Degradation at High Threads |
|---------------|-----------------|----------------------------|
| Single-core | 37,437 TPS at 32 threads | 32.2% loss at 2048 threads |
| Quad-core | 68,742 TPS at 64 threads | 33.3% loss at 2048 threads |
| **BetaPool** | 36,142 TPS | **96.5% of optimal** (automatic) |

BetaPool achieves near-optimal performance without manual tuning by detecting when thread scaling would cause GIL contention.

## Installation:

From PyPI:

```bash
pip install betapool
```

From source:

```bash
git clone https://github.com/RedZapdos123/BetaPool.git
cd BetaPool
pip install -e .
```

With optional dependencies:

```bash
pip install -e ".[dev]"      # Development tools.
pip install -e ".[numpy]"    # NumPy workload generators.
pip install -e ".[all]"      # All dependencies.
```

## Quick Start:

```python
from betapool import AdaptiveThreadPoolExecutor

# Drop-in replacement for ThreadPoolExecutor.
with AdaptiveThreadPoolExecutor(min_workers=4, max_workers=64) as executor:
    futures = [executor.submit(my_task, arg) for arg in args]
    results = [f.result() for f in futures]

    # Monitor adaptive behavior.
    metrics = executor.get_metrics()
    print(f"Current threads: {metrics['current_threads']}")
    print(f"Blocking ratio: {metrics['avg_blocking_ratio']:.2f}")
```

## The Blocking Ratio:

The core algorithm uses the **Blocking Ratio** metric:

```
beta = 1 - (cpu_time / wall_time)
```

- **beta near 1.0:** Thread is mostly waiting (I/O-bound). Safe to add threads.
- **beta near 0.0:** Thread is mostly computing (CPU-bound). Adding threads causes GIL contention.

## The GIL Safety Veto:

When beta falls below the danger threshold (default 0.3), the controller vetoes thread pool expansion:

```
if beta > threshold:    # I/O-bound work.
    scale_up()          # Safe to add threads.
else:
    hold()              # VETO: Prevents GIL thrashing.
```

This mechanism prevents the 32% throughput loss observed with naive thread scaling.

## API Reference:

**AdaptiveThreadPoolExecutor:**

```python
from betapool import AdaptiveThreadPoolExecutor, ControllerConfig

config = ControllerConfig(
    monitor_interval_sec=0.5,    # Metric check interval.
    beta_high_threshold=0.7,     # Scale up threshold.
    beta_low_threshold=0.3,      # GIL danger zone.
    scale_up_step=2,             # Threads to add.
    scale_down_step=1,           # Threads to remove.
)

with AdaptiveThreadPoolExecutor(
    min_workers=4,
    max_workers=64,
    config=config
) as executor:
    future = executor.submit(task_function, arg1, arg2)
    result = future.result()
```

**Methods:**

- `submit(fn, *args, **kwargs) -> Future`: Submit a task for execution.
- `map(fn, *iterables, timeout=None) -> Iterator`: Map function over iterables.
- `get_current_thread_count() -> int`: Get current active thread count.
- `get_metrics() -> Dict`: Get current metrics summary.
- `shutdown(wait=True)`: Shutdown the executor.

## Testing:

```bash
python -m pip install -e ".[dev]"
python -m pytest betapool/tests/ -v
```

## Release:

BetaPool uses semantic versions. Before publishing a release:

1. Update `version` in `pyproject.toml`.
2. Update `__version__` in `betapool/__init__.py`.
3. Add release notes to `CHANGELOG.md`.
4. Create and push a matching git tag, for example `v1.0.1`.
5. Publish a GitHub Release from that tag.

The `Publish to PyPI` GitHub Actions workflow builds the package and uploads it to PyPI when a GitHub Release is published. Add the PyPI API token to the GitHub repository secret named `PYPI_API_TOKEN`; never commit it to the repository.

Manual package validation:

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
```

## Research Paper:

**Read the full paper:** [Mitigating GIL Bottlenecks in Edge AI Systems (arXiv:2601.10582)](https://arxiv.org/pdf/2601.10582)

## Citation:

```bibtex
@article{mandal2026gilscheduler,
  title={Mitigating GIL Bottlenecks in Edge AI Systems: A Metric-Driven Adaptive Thread Pool},
  author={Mandal, Mridankan},
  journal={arXiv preprint arXiv:2601.10582},
  year={2026},
  url={https://arxiv.org/abs/2601.10582}
}
```

## License:

MIT License - see LICENSE file for details.
