跳转至

GFAsyncCompletion

API Reference / Standard / 类索引

  • 路径：addons/gf/standard/common/gf_async_completion.gd
  • 模块：Standard
  • 继承：RefCounted
  • API：public
  • 类别：运行时句柄 (runtime_handle)
  • 首次版本：7.0.0

一次性异步完成源。 用于把回调、Signal、后台任务或项目侧异步流程归一为 succeeded / failed / cancelled 终态。 它只保存结果状态，不调度任务，也不强制规定调用方如何重试或回滚。

成员概览

类型 名称 签名
信号 completed signal completed(completion: GFAsyncCompletion)
信号 succeeded signal succeeded(result: Variant, metadata: Dictionary)
信号 failed signal failed(error: String, metadata: Dictionary)
信号 cancelled signal cancelled(reason: StringName, metadata: Dictionary)
枚举 Status enum Status
方法 succeed func succeed(result: Variant = null, metadata: Dictionary = {}) -> bool:
方法 fail func fail(error: String = "", metadata: Dictionary = {}) -> bool:
方法 cancel func cancel(reason: StringName = &"cancelled", metadata: Dictionary = {}) -> bool:
方法 bind_cancel_token func bind_cancel_token(token: GFCancelToken) -> bool:
方法 wait_async func wait_async(options: Dictionary = {}) -> Dictionary:
方法 is_pending func is_pending() -> bool:
方法 is_completed func is_completed() -> bool:
方法 is_successful func is_successful() -> bool:
方法 is_failed func is_failed() -> bool:
方法 is_cancelled func is_cancelled() -> bool:
方法 get_status func get_status() -> Status:
方法 get_result func get_result() -> Variant:
方法 get_error func get_error() -> String:
方法 get_cancel_reason func get_cancel_reason() -> StringName:
方法 get_metadata func get_metadata() -> Dictionary:
方法 get_debug_snapshot func get_debug_snapshot() -> Dictionary:

信号

completed

  • API：public
  • 首次版本：7.0.0
signal completed(completion: GFAsyncCompletion)

完成源进入任意终态时发出。

参数：

名称 说明
completion 当前完成源。

succeeded

  • API：public
  • 首次版本：7.0.0
signal succeeded(result: Variant, metadata: Dictionary)

完成源成功时发出。

参数：

名称 说明
result 成功结果。
metadata 终态元数据。

结构：

  • result: Variant，调用方定义的成功结果。
  • metadata: Dictionary，调用方定义的终态元数据。

failed

  • API：public
  • 首次版本：7.0.0
signal failed(error: String, metadata: Dictionary)

完成源失败时发出。

参数：

名称 说明
error 失败说明。
metadata 终态元数据。

结构：

  • metadata: Dictionary，调用方定义的终态元数据。

cancelled

  • API：public
  • 首次版本：7.0.0
signal cancelled(reason: StringName, metadata: Dictionary)

完成源取消时发出。

参数：

名称 说明
reason 取消原因。
metadata 终态元数据。

结构：

  • metadata: Dictionary，调用方定义的终态元数据。

枚举

Status

  • API：public
  • 首次版本：7.0.0
enum Status {
    ## 等待完成。
    PENDING,
    ## 已成功完成。
    SUCCEEDED,
    ## 已失败。
    FAILED,
    ## 已取消。
    CANCELLED,
}

完成源状态。

方法

succeed

  • API：public
  • 首次版本：7.0.0
func succeed(result: Variant = null, metadata: Dictionary = {}) -> bool:

标记成功完成。

参数：

名称 说明
result 成功结果。
metadata 终态元数据。

返回：首次进入终态时返回 true。

结构：

  • result: Variant，调用方定义的成功结果。
  • metadata: Dictionary，调用方定义的终态元数据。

fail

  • API：public
  • 首次版本：7.0.0
func fail(error: String = "", metadata: Dictionary = {}) -> bool:

标记失败完成。

参数：

名称 说明
error 失败说明。
metadata 终态元数据。

返回：首次进入终态时返回 true。

结构：

  • metadata: Dictionary，调用方定义的终态元数据。

cancel

  • API：public
  • 首次版本：7.0.0
func cancel(reason: StringName = &"cancelled", metadata: Dictionary = {}) -> bool:

标记取消完成。

参数：

名称 说明
reason 取消原因。
metadata 终态元数据。

返回：首次进入终态时返回 true。

结构：

  • metadata: Dictionary，调用方定义的终态元数据。

bind_cancel_token

  • API：public
  • 首次版本：7.0.0
func bind_cancel_token(token: GFCancelToken) -> bool:

绑定取消 token；token 取消时完成源进入 cancelled 终态。

参数：

名称 说明
token 取消 token。

返回：成功绑定或 token 已经触发取消时返回 true。

wait_async

  • API：public
  • 首次版本：7.0.0
func wait_async(options: Dictionary = {}) -> Dictionary:

等待完成源进入终态。

参数：

名称 说明
options 等待选项，支持 GFAsyncWaitUtility.await_signal() 的选项。

返回：完成源快照；等待超时、取消或失效时包含 wait_status 字段。

结构：

  • options: Dictionary，可包含 timeout_seconds、cancel_token、guard_node、time_utility、respect_time_scale 和 timeout_warning。
  • return: Dictionary，包含 status、status_name、completed、result、error、cancel_reason、metadata 和可选 wait_status。

is_pending

  • API：public
  • 首次版本：7.0.0
func is_pending() -> bool:

当前是否仍在等待。

返回：等待中返回 true。

is_completed

  • API：public
  • 首次版本：7.0.0
func is_completed() -> bool:

当前是否已经进入任意终态。

返回：已完成、失败或取消时返回 true。

is_successful

  • API：public
  • 首次版本：7.0.0
func is_successful() -> bool:

当前是否成功。

返回：成功完成时返回 true。

is_failed

  • API：public
  • 首次版本：7.0.0
func is_failed() -> bool:

当前是否失败。

返回：失败时返回 true。

is_cancelled

  • API：public
  • 首次版本：7.0.0
func is_cancelled() -> bool:

当前是否取消。

返回：取消时返回 true。

get_status

  • API：public
  • 首次版本：7.0.0
func get_status() -> Status:

获取当前状态。

返回：当前状态枚举值。

get_result

  • API：public
  • 首次版本：7.0.0
func get_result() -> Variant:

获取成功结果。

返回：成功结果；未成功时为 null。

结构：

  • return: Variant，调用方定义的成功结果。

get_error

  • API：public
  • 首次版本：7.0.0
func get_error() -> String:

获取失败说明。

返回：失败说明。

get_cancel_reason

  • API：public
  • 首次版本：7.0.0
func get_cancel_reason() -> StringName:

获取取消原因。

返回：取消原因。

get_metadata

  • API：public
  • 首次版本：7.0.0
func get_metadata() -> Dictionary:

获取终态元数据副本。

返回：元数据副本。

结构：

  • return: Dictionary，调用方定义的终态元数据。

get_debug_snapshot

  • API：public
  • 首次版本：7.0.0
func get_debug_snapshot() -> Dictionary:

获取完成源状态快照。

返回：状态快照。

结构：

  • return: Dictionary，包含 status、status_name、completed、successful、failed、cancelled、result、error、cancel_reason、metadata、created_msec、completed_msec 和 duration_msec。