GFTimeoutController¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/common/gf_timeout_controller.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：运行时句柄 (
runtime_handle) - 首次版本：
7.0.0
可复用的超时取消控制器。 将“超时”建模为取消 token 的一种原因，并提供 start / reset / stop 的可复用生命周期。 它只负责产生超时信号和 token，不执行重试、回滚或业务流程。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | timed_out |
signal timed_out(reason: StringName, metadata: Dictionary) |
| 常量 | DEFAULT_TIMEOUT_REASON |
const DEFAULT_TIMEOUT_REASON: StringName = &"timeout" |
| 属性 | process_always |
var process_always: bool = true |
| 属性 | process_in_physics |
var process_in_physics: bool = false |
| 属性 | ignore_time_scale |
var ignore_time_scale: bool = false |
| 方法 | _init |
func _init() -> void: |
| 方法 | get_token |
func get_token() -> GFCancelToken: |
| 方法 | start_seconds |
func start_seconds( seconds: float, tree: SceneTree = null, reason: StringName = DEFAULT_TIMEOUT_REASON, metadata: Dictionary = {} ) -> GFCancelToken: |
| 方法 | stop |
func stop() -> void: |
| 方法 | reset |
func reset() -> GFCancelToken: |
| 方法 | cancel |
func cancel(reason: StringName = &"cancelled", metadata: Dictionary = {}) -> bool: |
| 方法 | is_cancelled |
func is_cancelled() -> bool: |
| 方法 | is_active |
func is_active() -> bool: |
| 方法 | is_timeout |
func is_timeout() -> bool: |
| 方法 | get_elapsed_msec |
func get_elapsed_msec() -> int: |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
信号¶
timed_out¶
- API：
public - 首次版本：
7.0.0
当前超时计划触发时发出。
参数：
| 名称 | 说明 |
|---|---|
reason |
超时取消原因。 |
metadata |
超时上下文。 |
结构：
metadata: Dictionary，包含调用方传入的超时上下文。
常量¶
DEFAULT_TIMEOUT_REASON¶
- API：
public - 首次版本：
7.0.0
默认超时原因。
属性¶
process_always¶
- API：
public - 首次版本：
7.0.0
是否在暂停时继续计时。
process_in_physics¶
- API：
public - 首次版本：
7.0.0
是否在物理帧中处理超时计时器。
ignore_time_scale¶
- API：
public - 首次版本：
7.0.0
是否忽略 Engine.time_scale。
方法¶
_init¶
- API：
public - 首次版本：
7.0.0
创建超时控制器。
get_token¶
- API：
public - 首次版本：
7.0.0
获取当前取消 token。
返回：当前超时控制器持有的 token。
start_seconds¶
- API：
public - 首次版本：
7.0.0
func start_seconds( seconds: float, tree: SceneTree = null, reason: StringName = DEFAULT_TIMEOUT_REASON, metadata: Dictionary = {} ) -> GFCancelToken:
启动一个新的超时计划。
参数：
| 名称 | 说明 |
|---|---|
seconds |
超时时间；小于等于 0 时立即超时。 |
tree |
可选 SceneTree；为空时使用当前主循环。 |
reason |
超时取消原因；为空时使用 timeout。 |
metadata |
超时上下文。 |
返回：当前计划使用的 token。
结构：
metadata: Dictionary，包含调用方定义的超时上下文。
stop¶
- API：
public - 首次版本：
7.0.0
停止当前超时计划，不取消 token。
reset¶
- API：
public - 首次版本：
7.0.0
重置为一个未取消 token，并清除超时状态。
返回：重置后的 token。
cancel¶
- API：
public - 首次版本：
7.0.0
主动取消当前 token。
参数：
| 名称 | 说明 |
|---|---|
reason |
取消原因。 |
metadata |
取消上下文。 |
返回：首次取消时返回 true。
结构：
metadata: Dictionary，包含调用方定义的取消上下文。
is_cancelled¶
- API：
public - 首次版本：
7.0.0
判断当前 token 是否已取消。
返回：已取消时返回 true。
is_active¶
- API：
public - 首次版本：
7.0.0
判断当前是否存在待触发的超时计划。
返回：存在活动超时计划时返回 true。
is_timeout¶
- API：
public - 首次版本：
7.0.0
判断最近一次取消是否来自超时计划。
返回：最近一次取消由超时触发时返回 true。
get_elapsed_msec¶
- API：
public - 首次版本：
7.0.0
获取当前超时计划已运行毫秒数。
返回：从 start_seconds 开始经过的毫秒数；未启动时为 0。
dispose¶
- API：
public - 首次版本：
7.0.0
释放当前计划和连接。
get_debug_snapshot¶
- API：
public - 首次版本：
7.0.0
获取超时控制器调试快照。
返回：调试快照。
结构：
return: Dictionary，包含 active、timed_out、timeout_seconds、elapsed_msec、reason、metadata 和 token。