fuchsia.component.runner

添加时间：7

PROTOCOLS

ComponentController

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

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

当受控组件实例终止或变得无法访问时 服务器会出于任何原因以墓碑关闭连接。

生命周期

组件可以处于以下两种状态之一：Started 或 Stopped。通过 组成部分在 ComponentRunner.Start() 被调用时为 Started 直到 ComponentRunner 关闭 ComponentController 句柄。通过 组件会过渡到 Stopped。

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

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

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

在停止之前，组件可以选择使用 OnEscrow 来存储一些 状态，以便在应用下次加载时再次接收这些状态， 。

当组件停止时，运行程序应发送 OnStop 事件 报告组件的终止状态，而不是只关闭渠道 （见下文）和（可选）退出代码。一旦运行程序发送 OnStop， 可以随意关闭 [ComponentRunner]；组件框架将关闭 则其会在收到此事件时结束频道。

旧版

运行程序关闭通道不发送 OnStop，而是合法 带有与终止状态相同的上一层楼方法，但这是一种传统方法 以实现更好的向后兼容性。

终止状态

终止状态指示了组件的最终处置方式， 。

请注意，终止状态并不与组件的退出代码同义。 组件的退出代码是运行程序报告的可选内容， 表示程序自身返回代码的整数。例如，对于 ELF 则是由 main() 返回的值。终止状态为 runner 的组件终止状态代码，这可以捕获 运行程序自身（而非 计划。

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

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

关闭

立即停止此组件实例。

ComponentRunner 必须立即终止组件实例， 然后以书写形式关闭此连接。建立连接后 关闭时，组件管理器会将该组件实例 停止，组件的命名空间将被拆除。

在某些情况下，可能会在 Stop() 之前发出 Kill()，但这不是 。

请求

<空>

OnEscrow

将部分组件状态存储在框架中，以便重新提交 传递给组件（一种称为 “托管”）。

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

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

通过 OnEscrow 托管的句柄始终会传递到下一个 组件执行情况

添加时间：HEAD

响应

名称类型
payload ComponentControllerOnEscrowRequest

OnPublishDiagnostics

运行程序将诊断信息发布到平台的事件。

此事件向平台发出信号，表示该事件的运行程序 组件正在发布有关 组件。组件管理器可以选择性地公开这些数据 。

响应

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

OnStop

报告组件已停止运行，以及有关组件终止的数据。这将 会使组件从生命周期过渡到 Stopped。

一旦运行程序发送 OnStop，即可随意关闭此 [ComponentRunner]； 组件框架会在收到此事件时关闭其通道末端。

或者，运行程序可以在没有此事件的情况下关闭控制器通道来发出信号 组件停止，但此方法为旧方法，不再推荐使用。

添加时间：HEAD

响应

名称类型
payload ComponentStopInfo

停止

请求停止组件实例。

停止组件实例后，服务器应关闭此 建立紧密联系。建立连接后 关闭时，组件管理器会将该组件实例 停止，组件的命名空间将被拆除。

请求

<空>

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 中定义

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

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

托管某个用户定义的状态。每当组件启动时 框架将通过 ComponentStartInfo.escrowed_dictionary.

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

示例

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

ComponentNamespaceEntry 资源

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

单个组件命名空间条目，用于描述命名空间装载点 (path) 以及支持它的目录 (directory)。这种类型通常是 组成。如需了解详情，请参阅 ComponentStartInfo.ns。

Ordinal字段类型说明
path string[4095]

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

在上述 path 处装载的目录。

ComponentStartInfo 资源

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

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

Ordinal字段类型说明
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/DictionaryRef

包含组件托管的数据和句柄的字典 调用 ComponentController.OnEscrow。

添加时间：HEAD

ComponentStopInfo 资源

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

Ordinal字段类型说明
termination_status zx/Status

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

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

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

运行程序实现者可以映射其运行时特定的退出代码概念 （例如 libc 退出状态）。他们也可能选择 请将此处留空

常量

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