RFC-0054：参数属性

“编写自记录型 API 的机会”

摘要

我们已经可以将属性应用于 FIDL 的各种元素，但不能应用于参数。这是一项扩展语法以接受参数属性的提案。

与其他 RFC 的关系

此 RFC 已被以下 RFC 取代：

• RFC-0050：语法修订

设计初衷

为更多语言元素添加属性可以提高语言一致性，并为未来的更多功能提供支持。无法在类型系统中编码的任何有关 API 的事实都可以改为在属性中编码。 无法在类型系统中编码的任何事实都可以在属性中以更结构化的方式捕获，从而简化各种后端中的后期验证。这些属性对于 linting 很有用，生成器还可以利用此信息生成更好的代码，或将其传播到目标语言的属性。这有助于对目标语言进行静态和/或动态分析。此外，属性还可以很好地用于为类型系统可能进行的扩展或改进制作原型。

此功能的主要用例是检查句柄泄漏、双重释放和释放后使用错误。

内核 ABI（即系统调用）也以 FIDL 格式表示，并且句柄的所有权通常不明确。用户是否应在 task_kill 系统调用后调用 handle_close？文档中并未明确说明。其他系统调用有非常明确的文档，但只能手动检查：

[Transport = "Syscall"]
protocol handle {
    /// Close a handle.
    /// Rights: None.
    handle_close(handle handle) -> (status status);

    /// Close a number of handles.
    /// Rights: None.
    handle_close_many(vector<handle> handles) -> (status status);

    /// Duplicate a handle.
    /// Rights: handle must have ZX_RIGHT_DUPLICATE.
    handle_duplicate(handle handle, rights rights) -> (status status, handle out);

    /// Replace a handle.
    /// Rights: None.
    handle_replace(handle handle, rights rights) -> (status status, handle out);
};

在为参数启用属性后，我们可以将注释替换为属性。这些属性与注释一样易于阅读，并且可以帮助 生成器生成可以使用静态和动态 分析工具（例如 这样）检查的代码。kazoo 工具可以 为 C 和 C++ 绑定生成相应的注解，使 Clang 静态分析器能够 捕获句柄误用错误。

该原型已在 Fuchsia 中发现许多 bug。

设计

该提案旨在向 FIDL 源语言添加参数属性。这些属性应以与其他属性类似的方式在 JSON IR 中公开。我们可能需要更新格式化程序。它不会影响线路格式。语言绑定仅受引入特定注解的影响，这些注解可能会更改生成的代码，但它们不会直接受到此提案的影响。

我们的提案仅更改了 FIDL 语法的一条生成规则：

- parameter = type-constructor , IDENTIFIER ;
+ parameter = ( attribute-list ) , type-constructor , IDENTIFIER ;

我们还需要诊断参数上的三斜杠文档或文档属性。

实现策略

此更改具有向后兼容性，无需迁移。有很多文档需要随该功能一起更新。此提案将更改解析器，并向 IR 添加新信息。引入新的参数属性后，可以单独对生成器进行潜在更改。

工效学设计

有可能使 FIDL API 更易于理解，并使绑定对静态和动态分析更加友好。额外的复杂性成本应该很低。如需查看包含潜在参数属性的示例，请参阅下一部分。 编辑器支持可能也需要进行小幅更新。

文档和示例

语法文档和语言参考需要进行小幅更新。我们可能需要添加一些样式指南，说明在某些情况下如何为参数属性换行。这可能不是很重要，因为当前样式指南中根本没有提及属性。

如需查看示例，请参阅设计初衷部分。

向后兼容性

此提案同时保持了 FIDL 源和线路 ABI 兼容性。稍后引入的特定属性可能会导致线路 ABI 不兼容。这些属性应单独通过 RFC 流程。

性能

未来的属性可能会对性能产生良好的影响。有关 API 的更多信息可能会帮助目标语言的优化器。

安全

特定属性可能会提高安全性，因为它们可以帮助目标语言中的静态和动态分析工具。

测试

我们将为 fidlc 编写测试，以确保正确解析，并为编译失败提供合理的诊断信息。生成的 JSON IR 也将进行测试。为了能够进行测试，我们需要引入至少一个适用于参数的属性。由于生成器最初不会被触及，因此不需要进行额外的测试。

缺点、替代方案和未知事项

实现成本相对较低。

RFC-0044 是一种可能的替代方案。接受该提案会在语言中引入一些不一致性，因为一种描述参数的方式将允许用户编写参数属性，而另一种方式则不允许。此外，RFC-0044 存在性能成本，因此某些协议（如系统调用）应谨慎使用或完全不使用。

在先技术和参考资料

Protobuf 具有 消息选项，其行为与参数属性有些类似。FIDL 已经为某些语言元素（如成员和协议）添加了属性。