GFMainThreadDispatchQueue¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/common/gf_main_thread_dispatch_queue.gd - 模块：
Standard - 继承：
GFUtility - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
7.0.0
主线程回调派发队列。 用于让后台线程、资源加载回调或项目侧异步流程把最终应用逻辑排回主线程。 队列只保存和派发 Callable，不创建线程、不校验线程身份，也不解释调用方的业务语义。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 属性 | max_callbacks_per_tick |
var max_callbacks_per_tick: int = 16: |
| 属性 | max_seconds_per_tick |
var max_seconds_per_tick: float = 0.0: |
| 方法 | init |
func init() -> void: |
| 方法 | tick |
func tick(_delta: float = 0.0) -> void: |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | post |
func post(callback: Callable, options: Dictionary = {}) -> int: |
| 方法 | post_owned |
func post_owned(owner: Object, callback: Callable, options: Dictionary = {}) -> int: |
| 方法 | dispatch |
func dispatch(max_count: int = 0, max_seconds: float = 0.0) -> Dictionary: |
| 方法 | cancel |
func cancel(handle: int) -> bool: |
| 方法 | cancel_owner |
func cancel_owner(owner: Object) -> int: |
| 方法 | clear |
func clear() -> void: |
| 方法 | mark_dispatch_context |
func mark_dispatch_context() -> void: |
| 方法 | has_dispatch_context |
func has_dispatch_context() -> bool: |
| 方法 | get_pending_count |
func get_pending_count() -> int: |
| 方法 | is_empty |
func is_empty() -> bool: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
属性¶
max_callbacks_per_tick¶
- API：
public - 首次版本：
7.0.0
tick() 每次最多派发多少个回调。
max_seconds_per_tick¶
- API：
public - 首次版本：
7.0.0
tick() 每次最多占用多少秒。小于等于 0 时不启用时间预算。
方法¶
init¶
- API：
public - 首次版本：
7.0.0
初始化队列，并标记该实例已有显式派发点。
tick¶
- API：
public - 首次版本：
7.0.0
按当前预算派发队列中的回调。
参数：
| 名称 | 说明 |
|---|---|
_delta |
为兼容 GF tick 签名而保留。 |
dispose¶
- API：
public - 首次版本：
7.0.0
清空队列。
post¶
- API：
public - 首次版本：
7.0.0
把回调加入主线程派发队列。
参数：
| 名称 | 说明 |
|---|---|
callback |
需要在显式派发点执行的回调。 |
options |
队列选项，支持 owner、metadata、label 和 front。 |
返回：派发句柄；callback 无效时返回 0。
结构：
options: Dictionary，可包含 owner: Object、metadata: Dictionary、label: String、front: bool。
post_owned¶
- API：
public - 首次版本：
7.0.0
把 owner 绑定回调加入主线程派发队列。owner 释放后回调会被跳过。
参数：
| 名称 | 说明 |
|---|---|
owner |
回调拥有者。 |
callback |
需要在显式派发点执行的回调。 |
options |
队列选项，支持 metadata、label 和 front。 |
返回：派发句柄；参数无效时返回 0。
结构：
options: Dictionary，可包含 metadata: Dictionary、label: String、front: bool。
dispatch¶
- API：
public - 首次版本：
7.0.0
派发队列中的回调。
参数：
| 名称 | 说明 |
|---|---|
max_count |
最大派发数量；小于等于 0 时不限制数量。 |
max_seconds |
最大派发秒数；小于等于 0 时不启用时间预算。 |
返回：派发报告。
结构：
return: Dictionary，包含 dispatched_count、failed_count、skipped_owner_count、pending_count、budget_exhausted 和 dispatch_context_marked。
cancel¶
- API：
public - 首次版本：
7.0.0
取消一个尚未派发的回调。
参数：
| 名称 | 说明 |
|---|---|
handle |
post() 返回的派发句柄。 |
返回：找到并取消时返回 true。
cancel_owner¶
- API：
public - 首次版本：
7.0.0
取消指定 owner 绑定的全部待派发回调。
参数：
| 名称 | 说明 |
|---|---|
owner |
回调拥有者。 |
返回：取消数量。
clear¶
- API：
public - 首次版本：
7.0.0
清空全部待派发回调和统计。
mark_dispatch_context¶
- API：
public - 首次版本：
7.0.0
标记该实例已有显式派发点。
has_dispatch_context¶
- API：
public - 首次版本：
7.0.0
当前实例是否已经标记显式派发点。
返回：已标记显式派发点时返回 true。
get_pending_count¶
- API：
public - 首次版本：
7.0.0
获取待派发数量。
返回：队列长度。
is_empty¶
- API：
public - 首次版本：
7.0.0
检查队列是否为空。
返回：队列为空时返回 true。
get_debug_snapshot¶
- API：
public - 首次版本：
7.0.0
获取队列调试快照。
返回：调试快照。
结构：
return: Dictionary，包含 pending_count、pending_handles、posted_count、dispatched_count、cancelled_count、failed_count、skipped_owner_count 和 dispatch_context_marked。