PAYATHON 2026

Godot 中 Caller 或 Callee 节点释放后,coroutine 会怎样?

数据小陈

结论

当 Caller.some_func() 直接执行 await callee.some_signal 时,Godot 有相应的状态清理机制。不过,这不能保证所有 Godot 4 版本在各种引用关系下都不会发生泄漏。

根据 Godot 4.7-stable 的实现:

  • Caller 被实际释放时,其 GDScript 实例会清理关联的挂起状态,断开等待连接,并处理保存的栈。
  • Callee 被实际释放时,发射端的 signal 连接会被移除。在没有额外引用或引用环的简单场景下,连接持有的 function state 会随之释放,其保存的栈也会被清理。
  • 这些清理不会让 await 后面的代码正常执行,也不会自动返回“已取消”的结果。

这里的 Caller 是定义并执行 some_func() 的脚本实例。仅释放更上层的调用节点,不能直接套用上述结论。相关实现可查阅 GDScript 实例析构代码和 GDScriptFunctionState 清理代码。

await 如何保存执行状态

Godot 4 内部仍使用 GDScriptFunctionState 保存挂起函数的状态,但脚本不能像旧版 yield 那样直接取得这个对象并手动恢复它。GDScript 的 await 文档中对此有说明。

等待 signal 时,VM 会保存函数状态,建立一个带有 CONNECT_ONE_SHOT 的 signal 连接,并在回调中绑定该状态的引用。signal 发出后,回调会恢复函数执行。具体实现见 Godot 4.7 的 await 指令。

保存的状态被回收,不代表等待中的函数已经完成。节点销毁可以触发状态回收,但不能代替 signal 发出,也不会执行 await 后面的资源释放或业务收尾代码。

为什么不同讨论会给出相反答案

Godot 的版本会影响结论,不能仅凭某个 PR 已合并就认为所有版本都安全。

Godot 曾修复过“中断的 coroutine 被删除后,局部对象没有清理”的问题。PR #116711列出了相关泄漏问题;随后 PR #117053又修正并简化了 coroutine 栈的清理。这些改动列在 Godot 4.7 更新记录中。

引擎断开连接,并不意味着历史版本完整释放了栈内所有值。讨论所用版本、局部变量持有的对象,以及是否存在多层 coroutine 等待,都会影响结论。

题目没有提供所提 PR 和讨论帖的链接,因此无法确认它们是否讨论同一个版本、同一种等待关系。

如何安排完成和取消

如果业务只需要在 signal 到达时处理一次结果,可以将普通回调连接到 Caller 的成员方法,避免为这一步建立挂起函数。下面假设 some_signal 带一个参数:

# Caller.gd
extends Node

func some_func(callee):
    if not is_instance_valid(callee):
        return
    if callee.is_queued_for_deletion():
        return

    if not callee.some_signal.is_connected(_on_some_signal):
        callee.some_signal.connect(_on_some_signal, CONNECT_ONE_SHOT)

func _on_some_signal(value):
    print(value)

这里连接的是 Caller 的成员方法。Caller 被释放后,连接会失效;Object.connect() 文档说明了 callable 所属对象被释放时的行为。Callee 被释放时,这个回调不会收到结果,也不会执行。

如果必须保留 await,而上层需要知道任务是否取消,应在业务层定义结束协议:

  1. 用明确的结果区分成功与取消,例如结束 signal 携带状态和结果。
  2. 在受控的节点销毁路径中,先结束或取消任务,让仍存活的等待方处理结果,再释放节点。
  3. 若任务需要跨场景或跨节点生命周期继续,由生命周期更长的管理对象保存任务状态,并在使用节点前检查其有效性。

普通 signal 默认会同步调用已连接的回调,因此应在发出结束 signal 前更新任务状态,防止恢复执行的代码再次触发同一任务。

容易遗漏的边界

queue_free() 只是安排删除。节点在当前帧末真正销毁之前,仍可能被访问,甚至继续发出 signal。remove_child() 也不等于释放节点。相关区别见 Node.queue_free() 文档。

在 await 后检查 is_instance_valid(callee),只能保护函数恢复后的访问。如果 Callee 被销毁导致 signal 永远不会发出,这个检查就没有机会执行,不能充当取消机制。

如果还有另一层函数执行 await some_func(callee),不要假定内部状态的清理会向上返回取消结果。需要让所有等待方结束的任务,应通过自己的结束协议传播取消。

排查泄漏时,应使用项目实际运行的 Godot 版本,分别复现 Caller 释放、Callee 释放,以及双方存活但 signal 始终不发出的情况。最后一种情况可能只是一个仍被引用的挂起任务;仅凭它没有恢复执行,还不足以判定引擎发生了内存泄漏。

备注:内容仅供参考。