fuchsia.component.runner

新增：7

协议

ComponentController

在 fuchsia.component.runner/component_runner.fidl 中定义

一种用于绑定和控制使用 ComponentRunner.Start() 启动的组件实例生命周期的协议。组件管理器是此协议的预期直接客户端。

当受控组件实例因任何原因终止或无法访问时，服务器会关闭连接并显示 epitaph。

生命周期

组件可能处于以下两种状态之一：Started 或 Stopped。从调用 ComponentRunner.Start() 到 ComponentRunner 关闭 ComponentController 句柄，组件一直处于 Started 状态。然后，组件会转换为 Stopped。

组件管理器使用 ComponentController 分两步终止组件：

  1. 组件管理器会调用 Stop()，以指示 ComponentRunner 应停止组件的执行并发送 OnStop 事件。
  2. 如果一段时间后 ComponentController 未关闭，组件管理器会调用 Kill()，以指示 ComponentRunner 必须立即停止组件的执行，然后发送 OnStop 事件。组件管理器可能会在调用 Kill() 后等待一段时间，然后再发送 OnStop，但不保证一定会等待或等待多长时间。

组件管理器会先等待 ComponentController 关闭，然后拆除它为已停止的组件托管的命名空间。组件管理器可能会在未先调用 Stop() 的情况下调用 Kill()。

在停止之前，组件可以选择使用 OnEscrow 在框架中存储一些状态，以便在下次启动时再次接收这些状态。

当组件停止时，运行程序应发送 OnStop 事件，而不仅仅是关闭通道，以报告组件的终止状态（见下文）和（可选）退出代码。运行程序发送 OnStop 后，便可自由关闭 [ComponentRunner]；组件框架在收到此事件后将关闭其通道端。

旧版

除了发送 OnStop 之外，运行程序还可以使用与终止状态相同的墓志铭关闭通道，但这是为了向后兼容而采用的旧方法，不再推荐使用。

终止状态

终止状态表示组件在运行程序眼中的最终处置。

请注意，终止状态与组件的退出代码不同。组件的退出代码（运行程序可选择是否报告）是一个整数，表示程序自己的返回代码。例如，对于 ELF 组件，它是 main() 返回的值。终止状态是运行程序针对组件终止的状态代码，该代码可能会捕获在运行程序本身（而非程序）的上下文中发生的故障模式。

服务器可能会在出错时发送以下终止状态：

  • ZX_OK：组件已成功退出，通常是因为组件被要求停止或组件自行决定退出。
  • INVALID_ARGUMENTS：
    • 此运行程序不支持 start_info.resolved_url；
    • start_info 包含缺失或无效的参数。
  • INSTANCE_CANNOT_START：运行程序无法启动组件。 例如，无法找到或加载程序的关键部分，或者引用的二进制文件对此运行程序无效。
  • RESOURCE_UNAVAILABLE：由于资源不足，无法启动组件。
  • INTERNAL：遇到意外的内部运行器错误。
  • INSTANCE_DIED：组件实例已启动，但随后因错误而终止。
  • 其他状态代码（例如 ZX_ERR_PEER_CLOSED）可能表示组件运行程序本身发生故障。组件管理器可能会通过终止组件运行器的作业来响应此类故障，以确保系统稳定性。

关闭

立即停止此组件实例。

ComponentRunner 必须立即终止组件实例，然后使用墓志铭关闭此连接。连接关闭后，组件管理器会将此组件实例视为已停止，并且组件的命名空间将被销毁。

在某些情况下，Kill() 可能会在 Stop() 之前发出，但无法保证。

请求

<EMPTY>

OnEscrow

将组件的部分状态存储在框架中，以便在下次启动组件时重新传递给组件（这种做法称为“托管”）。

当框架收到此事件时，它会等待组件的当前执行完成，然后在 outgoing_dir 上观察到 ZX_CHANNEL_READABLE 信号时再次启动组件。

重复调用会替换旧的托管值。不建议这样做。

通过 OnEscrow 托管的句柄始终会传递给组件的下一次执行。

Added: HEAD

响应

名称类型
payload ComponentControllerOnEscrowRequest

OnPublishDiagnostics

供运行器向平台发布诊断信息的事件。

此事件向平台发出信号，表明此组件的运行程序正在发布有关组件运行时的诊断信息。组件管理器可以选择向客户端公开此数据。

新增：27

响应

名称类型
payload ComponentDiagnostics

OnStop

报告组件已停止，并提供有关其终止的数据。这将导致组件进行生命周期转换，变为 Stopped。

运行程序发送 OnStop 后，便可自由关闭此 [ComponentRunner]；组件框架在收到此事件后将关闭其通道端。

或者，运行程序也可以在没有此事件的情况下关闭控制器通道，以指示组件停止，但此方法已过时，不再推荐使用。

Added: HEAD

响应

名称类型
payload ComponentStopInfo

停止

请求停止组件实例。

停止组件实例后，服务器应使用 epitaph 关闭此连接。连接关闭后，组件管理器会将此组件实例视为已停止，并且组件的命名空间将被销毁。

请求

<EMPTY>

ComponentRunner

在 fuchsia.component.runner/component_runner.fidl 中定义

用于运行组件的协议。

此协议由为其他组件提供运行时环境的组件实现。

注意：组件管理器是此接口的唯一预期直接客户端。

开始

开始运行 start_info 描述的组件实例。

组件管理器会绑定并使用 controller 来控制新启动的组件实例的生命周期。

错误通过 ComponentController 协议以 epitaph 的形式传递。如果发生错误，运行程序必须确保资源已清理。

请求

名称类型
start_info ComponentStartInfo
controller server_end:ComponentController

TaskProvider

在 fuchsia.component.runner/task_provider.fidl 中定义

由希望通过其运行时目录提供 Zircon 作业的运行程序提供。

Added: HEAD

GetJob

返回所请求组件的作业句柄。

成功后，返回一个与运行程序具有相同权限的句柄。

请求

<EMPTY>

响应

名称类型
payload TaskProvider_GetJob_Result

STRUCTS

TaskProvider_GetJob_Response 资源

在 fuchsia.component.runner/task_provider.fidl 中定义

字段类型说明默认
job handle<job> 无默认应用

TABLES

ComponentControllerOnEscrowRequest 资源

在 fuchsia.component.runner/component_runner.fidl 中定义

序数字段类型说明
outgoing_dir server_end:fuchsia.io/Directory

托管传出目录服务器端点。每当组件启动时，框架都会通过 ComponentStartInfo.outgoing_dir 返回此通道。
escrowed_dictionary fuchsia.component.sandbox/DictionaryRef

托管一些用户定义的状态。每当组件启动时，框架都会通过 ComponentStartInfo.escrowed_dictionary 返回这些句柄。

框架不会等待这些对象上的任何信号。

示例

假设某个组件需要托管一个事件对，该事件对表示某项高开销计算的结果。它可以创建一个字典，将事件对放入其中并使用适当的键（例如 "my_event_pair"），然后在启动时检查该条目。请注意，此方法已弃用，请改用 escrowed_dictionary_handle。
escrowed_dictionary_handle handle<eventpair>

托管一些用户定义的状态。每当组件启动时，框架都会通过 ComponentStartInfo.escrowed_dictionary 返回这些句柄。

框架不会等待这些对象上的任何信号。

示例

假设某个组件需要托管一个事件对，该事件对表示某项高开销计算的结果。它可以创建一个字典，将事件对放入其中并使用适当的键（例如 "my_event_pair"），然后在启动时检查该条目。
recoverable_bytes uint64

此组件停止运行时可恢复的字节数。用于跟踪组件托管时节省的内存量，仅用于开发目的。

ComponentDiagnostics 资源

在 fuchsia.component.runner/component_runner.fidl 中定义

新增：27

序数字段类型说明
tasks ComponentTasks

ComponentNamespaceEntry 资源

在 fuchsia.component.runner/component_runner.fidl 中定义

单个组件命名空间条目，用于描述命名空间装载点 (path) 及其后备目录 (directory)。此类型通常在向量内组合。如需了解详情，请参阅 ComponentStartInfo.ns。

序数字段类型说明
path string:4095

目录的装载点，包括前导斜杠。例如：“/pkg”“/svc”或“/config/data”。
directory client_end:fuchsia.io/Directory

装载在上述 path 处的目录。

ComponentStartInfo 资源

在 fuchsia.component.runner/component_runner.fidl 中定义

用于启动新组件实例的参数。

序数字段类型说明
resolved_url fuchsia.url/Url

组件的网址。由于历史原因，称为 resolved_url，而不仅仅是 url。
program fuchsia.data/Dictionary

组件的程序声明。 此信息来自ComponentDecl.program。
ns vector<ComponentNamespaceEntry>:32

要提供给组件实例的命名空间。

命名空间指定组件实例在启动时接收的目录集。通过命名空间目录，组件可以访问其可用的功能。命名空间的内容主要由组件的 use 声明决定，但也可能包含框架自动提供的其他功能。

按照惯例，组件的命名空间通常包含以下部分或全部目录：

  • “/svc”：一个目录，其中包含组件通过其“import”声明请求使用的服务。
  • “/pkg”：包含组件软件包（包括其二进制文件、库和其他资源）的目录。

每个条目中指定的装载点必须是唯一的且不重叠。例如，[{"/foo", ..}, {"/foo/bar", ..}] 无效。
outgoing_dir server_end:fuchsia.io/Directory

此组件提供服务的目录。
runtime_dir server_end:fuchsia.io/Directory

运行程序提供的目录，用于显示组件的运行时信息。运行程序必须提供该数据，或将其丢弃，以避免无限期地阻塞任何使用方。
numbered_handles vector<fuchsia.process/HandleInfo>:128

传递给组件的带编号的句柄。

如果组件不支持编号句柄，则运行程序应关闭这些句柄。
encoded_config fuchsia.mem/Data

组件配置的二进制表示法。

布局

数据的前 2 个字节应解读为无符号 16 位小端序整数，表示其后包含配置校验和的字节数。在校验和之后，所有剩余字节都是顶级结构的持久性 FIDL 消息。该结构的字段与组件已编译清单的配置字段匹配，且顺序相同。
break_on_start handle<eventpair>

调试程序可用于推迟组件启动的事件对。

例如，ELF 运行程序会推迟在组件中创建进程，直到此事件对上发出 ZX_EVENTPAIR_PEER_CLOSED 信号。它们还可确保在等待此 eventpair 之前提供 runtime_dir。 ELF 调试程序可以查询 runtime_dir，以决定是否在丢弃 eventpair 的另一端之前进行附加，该 eventpair 在 fuchsia.component.events 中的 DebugStarted 事件的载荷中发送。
component_instance handle<event>

一个不透明令牌，用于表示组件实例。

fuchsia.component/Introspector 协议可用于从此令牌获取实例的字符串名字对象。

运行程序可能会将此令牌作为诊断信息的一部分发布，以便在不知道其名字对象的情况下识别正在运行的组件。

当组件实例被销毁时，令牌会失效。

Added: HEAD
escrowed_dictionary fuchsia.component.sandbox/DictionaryRef

一个字典，其中包含组件在之前执行期间通过 ComponentController.OnEscrow 托管的数据和句柄。请注意，此字段已被弃用，请改用 escrowed_dictionary_handle。

Added: HEAD
escrowed_dictionary_handle handle<eventpair>

一个字典，其中包含组件在之前通过 ComponentController.OnEscrow 执行期间托管的数据和句柄。

Added: HEAD

ComponentStopInfo 资源

在 fuchsia.component.runner/component_runner.fidl 中定义

序数字段类型说明
termination_status zx/Result

组件的终止状态，如上文 [ComponentRunner] 中所述。

调用方应设置此字段。如果缺少该值，框架将假定值为 ZX_OK。
exit_code int64

（可选）组件实例的退出代码。

运行程序实现者可以将特定于运行时的退出代码概念（例如 libc 退出状态）映射到此字段。也可以选择留空

ComponentTasks 资源

在 fuchsia.component.runner/component_runner.fidl 中定义

新增：27

序数字段类型说明
component_task Task
parent_task Task

UNIONS

任务灵活 资源

在 fuchsia.component.runner/component_runner.fidl 中定义

新增：27
序数变体类型说明
job handle<job>
process handle<process>
thread handle<thread>

TaskProvider_GetJob_Result strict resource

在 fuchsia.component.runner/task_provider.fidl 中定义

序数变体类型说明
response TaskProvider_GetJob_Response
err zx/Status

常量

名称值类型说明
MAX_HANDLE_COUNT 128 uint32
MAX_NAMESPACE_COUNT 32 uint32