fuchsia.component.runner

添加次数：7

协议

ComponentController

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

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

当受控组件实例因任何原因而终止或变得无法访问时，服务器会关闭带有 epitaph 的连接。

生命周期

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

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

  1. 组件管理器会调用 Stop()，以表明 ComponentRunner 应停止组件的执行，并以 epitaph 形式关闭此连接。
  2. 如果一段时间后 ComponentController 未关闭，组件管理器会调用 Kill() 来指示 ComponentRunner 必须立即停止组件的执行，然后以表格式关闭此连接。组件管理器可能会在调用 Kill() 后等待一段时间，然后再关闭 ComponentController 通道，但无法保证它会等待或等待多长时间。

组件管理器首先会等待 ComponentController 关闭，然后删除它为已停止的组件托管的命名空间。组件管理器可以直接调用 Kill()，而不必先调用 Stop()。

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

EPITAPH

此协议会发送 FIDL 副本，指示组件实例已终止。组件运行程序应在关闭连接之前清理归因于该组件的所有资源。

服务器可能会错误地发送以下墓碑：

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

关闭

立即停止此组件实例。

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

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

请求

<EMPTY>

OnEscrow

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

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

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

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

添加了：HEAD

响应

名称类型
payload ComponentControllerOnEscrowRequest

OnPublishDiagnostics

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

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

响应

名称类型
payload fuchsia.diagnostics.types/ComponentDiagnostics

停止

请求停止组件实例。

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

请求

<EMPTY>

ComponentRunner

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

用于运行组件的协议。

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

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

开始

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

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

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

错误数：

请求

名称类型
start_info ComponentStartInfo
controller server_end<ComponentController>

表

ComponentControllerOnEscrowRequest 资源

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

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

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

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

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

示例

假设某个组件需要托管一个事件对，它表示某种开销很高的计算的结果。它可以创建一个字典，将事件对放入相应的键（例如 "my_event_pair"）中，然后在启动时检查是否有该条目。

Component 命名空间 Entry 资源

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

单个组件命名空间条目，用于说明命名空间装载点 (path) 和支持该点的目录 (directory)。此类型通常包含在矢量内。如需了解详情，请参阅 ComponentStartInfo.ns。

序数字段类型说明
path string[4095]

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

装载在上述 path 中的目录。

ComponentStartInfo 资源

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

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

序数字段类型说明
resolved_url fuchsia.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 信号。它们还会确保在等待此事件对之前提供 Runtime_dir。ELF 调试程序可以查询 Runtime_dir，以便在丢弃事件对的另一端之前是否连接（位于 fuchsia.component.events 中 DebugStarted 事件的载荷中发送）。
component_instance handle<event>

表示组件实例的不透明令牌。

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

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

组件实例被销毁后，令牌即失效。

添加了：HEAD
escrowed_dictionary fuchsia.component.sandbox/Dictionary

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

添加了：HEAD

常量

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