Metadata-Version: 2.3
Name: voidrail
Version: 0.3.2
Summary: 
Author: arcstep
Author-email: 43801@qq.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: async-timeout (>=5.0.1,<6.0.0)
Requires-Dist: celery (>=5.5.2,<6.0.0)
Requires-Dist: click (>=8.1.8,<9.0.0)
Requires-Dist: redis (>=6.0.0,<7.0.0)
Description-Content-Type: text/markdown

# VoidRail

VoidRail 的名称来自于古老的修仙界，是虚空传送阵的意思。

VoidRail 基于 Celery 构建轻量级分布式任务处理框架，专为 CPU 密集型计算设计。它提供简单易用的接口，让您可以快速构建和部署分布式计算服务。

## 安装

使用 pip 安装：

```bash
pip install voidrail
```

## 核心组件

VoidRail 采用两组件架构：

1. **Worker**：服务实现模块，继承 `CeleryWorker` 基类，定义处理逻辑
2. **Client**：客户端模块，使用 `CeleryClient` 类发送任务请求

## 基本使用

### 简单例子

```python
import sys
import os
import time
from voidrail import app, start_worker, get_config

@app.task(name='hello.say_hello')
def say_hello(name):
    """简单的问候任务"""
    return f"Hello, {name}! Current time: {time.ctime()}"

@app.task(name='hello.say_hello_delay', bind=True)
def say_hello_delay(self, name, delay=3):
    """带延迟的问候任务，演示任务状态更新"""
    self.update_state(state='PROGRESS', meta={'progress': 0, 'message': '开始处理'})
    
    # 模拟处理过程
    for i in range(10):
        time.sleep(delay / 10)
        self.update_state(state='PROGRESS', meta={
            'progress': (i + 1) * 10, 
            'message': f'处理中 {(i + 1) * 10}%'
        })
    
    return f"Hello after {delay} seconds, {name}! Time: {time.ctime()}"

def main():
    """命令行入口点"""
    # 显示服务信息
    config = get_config()
    print(f"Broker URL: {config['broker_url']}")
    print(f"后端 URL: {config['result_backend']}")
    
    # 启动Worker
    start_worker()

if __name__ == "__main__":
    main()

```

### 使用客户端

```python
import sys
import os
import time
import json
from voidrail.config import get_config
from voidrail.client import CeleryClient

# 创建客户端
client = CeleryClient(service_name="hello")

# 同步调用
result = client.call(
    task_name="say_hello",
    args=["World"]
)
print(result["result"])  # 输出: Hello, World!

# 异步调用
async_result = client.call(
    task_name="say_hello_delay",
    args=["Async World"],
    kwargs={"delay": 2},
    wait_result=False
)
task_id = async_result["task_id"]

# 检查任务状态
status = client.get_task_status(task_id)
```

### 水平扩展能力

VoidRail的一个主要优势是支持简单而强大的水平扩展。当您启动多个相同服务的Worker实例时：

1. **自动负载均衡**：所有实例会自动协作处理队列中的任务
2. **无需额外配置**：不需要任何特殊设置，只需启动更多相同的服务实例
3. **容错和高可用**：如果某个实例崩溃，其他实例会继续处理任务

例如，您可以在多台服务器上启动相同的服务：

```mermaid
graph TB
    Client[客户端]
    Queue[(Redis消息队列)]
    
    subgraph "服务器A"
    Worker1[Worker实例1]
    end
    
    subgraph "服务器B"
    Worker2[Worker实例2]
    Worker3[Worker实例3]
    end
    
    subgraph "服务器C"
    Worker4[Worker实例4]
    end
    
    Client -->|发送任务| Queue -->|分发任务| Worker1 & Worker2 & Worker3 & Worker4
```

## 运行多个Worker实例

要充分利用多核CPU，可以启动多个Worker实例：

```bash
# 启动Worker进程
# 通过环境变量控制并发度
CELERY_CONCURRENCY=4 python hello_service.py
```

您可以在不同的服务器上多次启动相同的服务实例：

```bash
# 在服务器A上
python hello_service.py

# 在服务器B上
python hello_service.py

# 在服务器C上
python hello_service.py
```

每个实例都会自动加入相同的worker池，共同处理任务队列。Celery会为每个worker分配一个唯一ID，
确保任务只会被处理一次。这种设计使VoidRail非常适合需要动态扩展的场景 - 随着负载增加，
只需启动更多的worker实例即可线性提高处理能力。

