GFJobQueueUtility¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/jobs/gf_job_queue_utility.gd - 模块：
Standard - 继承：
GFUtility - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
通用任务队列工具。 提供等待、激活、完成、失败、取消、进度和调试快照能力。 队列不绑定执行线程或业务语义，具体执行由调用方决定。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | job_enqueued |
signal job_enqueued(job: GFJob) |
| 信号 | job_started |
signal job_started(job: GFJob) |
| 信号 | job_progressed |
signal job_progressed(job: GFJob, progress: float, message: String) |
| 信号 | job_completed |
signal job_completed(job: GFJob) |
| 信号 | job_failed |
signal job_failed(job: GFJob) |
| 信号 | job_cancelled |
signal job_cancelled(job: GFJob) |
| 属性 | max_completed_jobs |
var max_completed_jobs: int = 64 |
| 属性 | max_failed_jobs |
var max_failed_jobs: int = 64 |
| 方法 | init |
func init() -> void: |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | enqueue |
func enqueue( queue_name: StringName = &"default", data: Variant = null, metadata: Dictionary = {}, front: bool = false ) -> GFJob: |
| 方法 | start_next_job |
func start_next_job(queue_name: StringName = &"default") -> GFJob: |
| 方法 | run_next_job |
func run_next_job(queue_name: StringName, processor: Callable) -> GFJob: |
| 方法 | update_job_progress |
func update_job_progress(job_id: StringName, progress: float, message: String = "") -> bool: |
| 方法 | complete_job |
func complete_job(job_id: StringName, result: Variant = null) -> bool: |
| 方法 | fail_job |
func fail_job(job_id: StringName, error_message: String = "", result: Variant = null) -> bool: |
| 方法 | cancel_job |
func cancel_job(job_id: StringName) -> bool: |
| 方法 | pause_queue |
func pause_queue(queue_name: StringName = &"default") -> void: |
| 方法 | resume_queue |
func resume_queue(queue_name: StringName = &"default") -> void: |
| 方法 | is_queue_paused |
func is_queue_paused(queue_name: StringName = &"default") -> bool: |
| 方法 | get_job |
func get_job(job_id: StringName) -> GFJob: |
| 方法 | get_waiting_jobs |
func get_waiting_jobs(queue_name: StringName = &"default") -> Array[GFJob]: |
| 方法 | clear_queue |
func clear_queue(queue_name: StringName = &"default", cancel_jobs: bool = true) -> void: |
| 方法 | clear_all |
func clear_all() -> void: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
信号¶
job_enqueued¶
- API：
public
任务进入等待队列时发出。
参数：
| 名称 | 说明 |
|---|---|
job |
任务记录。 |
job_started¶
- API：
public
任务开始执行时发出。
参数：
| 名称 | 说明 |
|---|---|
job |
任务记录。 |
job_progressed¶
- API：
public
任务进度变化时发出。
参数：
| 名称 | 说明 |
|---|---|
job |
任务记录。 |
progress |
当前进度。 |
message |
进度说明。 |
job_completed¶
- API：
public
任务完成时发出。
参数：
| 名称 | 说明 |
|---|---|
job |
任务记录。 |
job_failed¶
- API：
public
任务失败时发出。
参数：
| 名称 | 说明 |
|---|---|
job |
任务记录。 |
job_cancelled¶
- API：
public
任务取消时发出。
参数：
| 名称 | 说明 |
|---|---|
job |
任务记录。 |
属性¶
max_completed_jobs¶
- API：
public
保留的完成任务数量。
max_failed_jobs¶
- API：
public
保留的失败任务数量。
方法¶
init¶
- API：
public
初始化任务队列工具并清空运行时状态。
dispose¶
- API：
public
释放任务队列工具持有的运行时状态。
enqueue¶
- API：
public
func enqueue( queue_name: StringName = &"default", data: Variant = null, metadata: Dictionary = {}, front: bool = false ) -> GFJob:
追加一个等待任务。
参数：
| 名称 | 说明 |
|---|---|
queue_name |
队列名。 |
data |
任务输入数据。 |
metadata |
项目自定义元数据。 |
front |
是否插入到队列头部。 |
返回：新任务记录。
结构：
data: Variant，项目侧任务输入载荷。metadata: Dictionary，复制到新建 GFJob 的元数据。
start_next_job¶
- API：
public
从队列取出下一个等待任务并标记为执行中。
参数：
| 名称 | 说明 |
|---|---|
queue_name |
队列名。 |
返回：任务记录；没有可执行任务时返回 null。
run_next_job¶
- API：
public
使用回调立即处理下一个等待任务。回调返回 false 或 ok=false 字典时标记失败。
参数：
| 名称 | 说明 |
|---|---|
queue_name |
队列名。 |
processor |
任务处理回调。 |
返回：被处理的任务；没有可执行任务时返回 null。
update_job_progress¶
- API：
public
更新任务进度。
参数：
| 名称 | 说明 |
|---|---|
job_id |
任务 ID。 |
progress |
当前进度。 |
message |
进度说明。 |
返回：更新成功返回 true。
complete_job¶
- API：
public
标记任务完成。
参数：
| 名称 | 说明 |
|---|---|
job_id |
任务 ID。 |
result |
任务结果。 |
返回：完成成功返回 true。
结构：
result: Variant，项目侧任务结果载荷。
fail_job¶
- API：
public
标记任务失败。
参数：
| 名称 | 说明 |
|---|---|
job_id |
任务 ID。 |
error_message |
错误文本。 |
result |
可选失败结果。 |
返回：标记成功返回 true。
结构：
result: Variant，项目侧失败结果载荷。
cancel_job¶
- API：
public
取消任务。
参数：
| 名称 | 说明 |
|---|---|
job_id |
任务 ID。 |
返回：取消成功返回 true。
pause_queue¶
- API：
public
暂停指定队列。
参数：
| 名称 | 说明 |
|---|---|
queue_name |
队列名。 |
resume_queue¶
- API：
public
恢复指定队列。
参数：
| 名称 | 说明 |
|---|---|
queue_name |
队列名。 |
is_queue_paused¶
- API：
public
检查队列是否暂停。
参数：
| 名称 | 说明 |
|---|---|
queue_name |
队列名。 |
返回：暂停时返回 true。
get_job¶
- API：
public
获取任务。
参数：
| 名称 | 说明 |
|---|---|
job_id |
任务 ID。 |
返回：任务记录；不存在时返回 null。
get_waiting_jobs¶
- API：
public
获取队列中的等待任务。
参数：
| 名称 | 说明 |
|---|---|
queue_name |
队列名。 |
返回：等待任务列表副本。
clear_queue¶
- API：
public
清空指定队列中的等待任务。
参数：
| 名称 | 说明 |
|---|---|
queue_name |
队列名。 |
cancel_jobs |
是否把等待任务标记为取消。 |
clear_all¶
- API：
public
清空全部队列与历史任务。
get_debug_snapshot¶
- API：
public
获取调试快照。
返回：调试快照字典。
结构：
return: Dictionary，包含 job_count、queue_count、completed_count、failed_count，以及以队列名为键的 queues。