GFAsyncTrackerUtility¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/debug/gf_async_tracker_utility.gd - 模块：
Standard - 继承：
GFUtility - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
7.0.0
可选异步句柄追踪工具。 默认关闭。启用后可登记异步完成源、通道、超时控制器或项目自定义句柄， 并通过弱引用生成活动句柄快照，帮助诊断未完成、未释放或异常停留的异步流程。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | async_handle_tracked |
signal async_handle_tracked(tracking_id: int, label: StringName) |
| 信号 | async_handle_untracked |
signal async_handle_untracked(tracking_id: int, label: StringName) |
| 常量 | DEFAULT_MAX_STACK_TRACE_CHARS |
const DEFAULT_MAX_STACK_TRACE_CHARS: int = 4000 |
| 属性 | tracking_enabled |
var tracking_enabled: bool = false |
| 属性 | stack_trace_enabled |
var stack_trace_enabled: bool = false |
| 属性 | max_stack_trace_chars |
var max_stack_trace_chars: int = DEFAULT_MAX_STACK_TRACE_CHARS: |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | track_handle |
func track_handle( handle: Object, label: StringName = &"", metadata: Dictionary = {}, snapshot_provider: Callable = Callable() ) -> int: |
| 方法 | untrack_id |
func untrack_id(tracking_id: int) -> bool: |
| 方法 | untrack_handle |
func untrack_handle(handle: Object) -> int: |
| 方法 | clear_invalid |
func clear_invalid() -> int: |
| 方法 | clear |
func clear() -> void: |
| 方法 | check_and_reset_dirty |
func check_and_reset_dirty() -> bool: |
| 方法 | get_active_records |
func get_active_records(include_invalid: bool = false) -> Array[Dictionary]: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
信号¶
async_handle_tracked¶
- API：
public - 首次版本：
7.0.0
句柄被登记时发出。
参数：
| 名称 | 说明 |
|---|---|
tracking_id |
追踪 ID。 |
label |
追踪标签。 |
async_handle_untracked¶
- API：
public - 首次版本：
7.0.0
句柄被移除追踪时发出。
参数：
| 名称 | 说明 |
|---|---|
tracking_id |
追踪 ID。 |
label |
追踪标签。 |
常量¶
DEFAULT_MAX_STACK_TRACE_CHARS¶
- API：
public - 首次版本：
7.0.0
默认堆栈文本最大长度。
属性¶
tracking_enabled¶
- API：
public - 首次版本：
7.0.0
是否启用追踪。关闭时 track_handle 直接返回 0。
stack_trace_enabled¶
- API：
public - 首次版本：
7.0.0
是否在登记时捕获调用堆栈。
max_stack_trace_chars¶
- API：
public - 首次版本：
7.0.0
单条堆栈文本最大长度。
方法¶
dispose¶
- API：
public - 首次版本：
7.0.0
清除所有追踪记录。
track_handle¶
- API：
public - 首次版本：
7.0.0
func track_handle( handle: Object, label: StringName = &"", metadata: Dictionary = {}, snapshot_provider: Callable = Callable() ) -> int:
登记一个异步句柄。
参数：
| 名称 | 说明 |
|---|---|
handle |
待追踪对象。 |
label |
稳定标签；为空时使用 handle.get_class()。 |
metadata |
追踪上下文。 |
snapshot_provider |
可选无参快照回调；返回值会收窄为 Dictionary。 |
返回：追踪 ID；未启用或 handle 为空时返回 0。
结构：
metadata: Dictionary，包含调用方定义的追踪上下文。
untrack_id¶
- API：
public - 首次版本：
7.0.0
按追踪 ID 取消登记。
参数：
| 名称 | 说明 |
|---|---|
tracking_id |
追踪 ID。 |
返回：成功移除时返回 true。
untrack_handle¶
- API：
public - 首次版本：
7.0.0
移除指定对象的所有追踪记录。
参数：
| 名称 | 说明 |
|---|---|
handle |
待移除对象。 |
返回：移除数量。
clear_invalid¶
- API：
public - 首次版本：
7.0.0
清除已经失效的弱引用记录。
返回：清除数量。
clear¶
- API：
public - 首次版本：
7.0.0
清空所有追踪记录。
check_and_reset_dirty¶
- API：
public - 首次版本：
7.0.0
判断是否存在未读取的追踪变更，并重置 dirty 标记。
返回：自上次调用以来有追踪变化时返回 true。
get_active_records¶
- API：
public - 首次版本：
7.0.0
获取活动追踪记录快照。
参数：
| 名称 | 说明 |
|---|---|
include_invalid |
是否包含弱引用已失效的记录。 |
返回：追踪记录数组。
结构：
return: Array[Dictionary]，每项包含 tracking_id、label、valid、age_msec、metadata 和可选 snapshot / stack_trace。
get_debug_snapshot¶
- API：
public - 首次版本：
7.0.0
获取追踪调试快照。
返回：调试快照。
结构：
return: Dictionary，包含 enabled、active_count、invalid_count、dirty 和 records。