diff --git a/Home.md b/Home.md index e6afd1f..d800023 100644 --- a/Home.md +++ b/Home.md @@ -183,4 +183,64 @@ scheduler.update_listen_data("on_config_changed", "dark_mode=true") # ... 主程序继续运行 ... # 当需要关闭时: # scheduler.stop_queue_scheduler() -``` \ No newline at end of file +``` + +## 详细使用指南 + +### 消息优先级的使用 + +### 设置任务过期时间 + +### 错误处理与重试机制 + +### 如何扩张分片数 + +### 监听器的高级用法 + +## API 文档 + +`MessageItem` + +- `to_dict() -> Dict`:转化为字典 +- `to_dict_by_core() -> Dict`:转换为核心库所需的格式(字符串化的 JSON)。 +- `classmethod from_dict(data: Dict) -> MessageItem`:从字典创建对象。 +- `is_expired() -> bool`:检查消息是否过期。 + +`QueueScheduler` + +- `__init__(receive_thread_num=1, task_thread_num=1, shard_num=4)` +- `start_queue_scheduler()`:启动所有后台线程。 +- `stop_queue_scheduler()`:停止所有后台线程。 +- `send_message(message: MessageItem, callback: Callable)`:发送任务。 +- `update_listen_data(key: str, value: Any)`:更新监听数据。 +- `get_listen_data(key: str) -> Any`:获取监听数据当前值。 + +### 装饰器 + +- `@TaskMounter.task(meta: dict = {})` +- `@ListenMounter.listener()` + +## 性能调优 + +1. **分片 (`shard_num`)**:这是最重要的参数。根据你的工作负载和 CPU 核心数增加分片(例如 8,16),可以显著提高入队/出队的吞吐量。 +2. **线程数**:`task_thread_num` 应根据任务类型(I/O 密集型或 CPU 密集型)进行调整。 +3. **SQLite 优化**:Rust 核心层已经设置了积极的 PRAGMA 选项(WAL,NORMAL sync,大缓存)。除非非常了解,否则不建议修改。 +4. **消息大小**:保持 `MessageItem.content` 尽可能小,大的数据应该存储在其他地方(如 S3、数据库),只在消息中存储引用 ID。 + +## 常见问题 + +**Q:任务函数执行失败了怎么办?** +A:任务状态会被标记为 `FAILED`。根据 `retry_count` 和你的逻辑,你可以选择重新发送该消息 + +**Q:如何查询队列中当前的任务数量** +A:使用 `scheduler.queue_operation.get_queue_length()`。 + +**Q:如何手动触发清理?** +A:可以调用 `scheduler.cleanup_scheduler.cleanup_expired_message()`,但通常清理调度器会自动处理。 + +*Q:编译 Rust 扩展时出错?* +A:确保你的 Rust 工具链是最新的 (`rustup update`)。在 Windows 上,你可能需要安装 Microsoft C++ Build Tools。 + +*Q:`destination 找不到对应的任务函数`?* +A:确保任务函数被正确装饰(`@TaskMounter.task`)并且其 `__name__` 与 `destination` 字符串完全一致。确保包含任务函数的模块在运行主程序前已被导入。 +