RFC-0231：FIDL 版本管理取代語法

RFC-0231：FIDL 版本管理替換語法
狀態已接受
領域
  • FIDL
說明

為 @available 屬性新增 replace=N 引數
問題
更小鳥
作者
審查人員
提交日期 (年月分)2023-09-26
審查日期 (年-月-日)2023 年 10 月 24 日

編輯這個 RFC

編輯 RFC 中繼資料

摘要

變更 FIDL 的 @available 屬性，以支援 replaced 引數。這與 removed 類似，但會驗證取代版本是否在同一版本為 added。

背景

RFC-0083：FIDL 版本管理推出了用於版本 FIDL API 的 @available 屬性。該設計的其中一項規定是允許版本化所有可能的變更。換句話說，應在單一 versioned.fidl 檔案中表示 v1.fidl 轉換為任意不同的 v2.fidl。我們的設計要求允許多個元素使用相同名稱，前提是其版本範圍不會重疊。

舉例來說，考慮將 @discoverable 屬性新增至第 5 版通訊協定 P。我們無法直接以 @available 表示，因為屬性無法放在其他屬性上。然而，我們可以改為執行以下動作：

@available(added=1, removed=5)
protocol P {};

@available(added=5)
@discoverable
protocol P {};

這種從相同版本中移除元素並重新加回該元素的技術，稱為「切換」。

提振精神

新增、淘汰和移除 API 的一般生命週期的語法相當直覺。另一方面，「切換」模式則不一定。向他人說明時也很合理，但這是需要說明的隱藏功能。在上述範例中，您可以指定 removed=5，實際上意味著通訊協定已經從第 5 版中移除，尤其是在原始碼中不相鄰的 added=5 時，更是如此。

區分取代和移除功能也有助於移除舊版功能，並替換為更通用的解決方案。這是另外的提案：RFC-0232：多個 API 級別的 FIDL 繫結。

相關人員

講師：abarth@google.com

審查者：hjfreyer@google.com、ianloic@google.com、ddorwin@google.com

諮詢對象：Wez@google.com、sethladd@google.com、wilkinsonclay@google.com

社會化：我在撰寫 RFC 之前，與 FIDL 團隊和平台版本管理工作小組討論了這個概念。

設計

  • 加入名為 replaced 的新 @available 引數。運作方式與 removed 相同，但具有不同的驗證方式，如下所述。可用於在 library 宣告以外的任何元素上使用 removed。

  • 元素標示為 removed=N 後，請確認「並未」另一個使用相同名稱並標示為 added=N 的元素。

  • 元素標示為 replaced=N 後，請驗證「IS」IS有另一個名稱相同的元素標示為 added=N。

  • 這項驗證僅適用於直接標示為 removed 或 replaced 的元素，不適用於「繼承」引數的子項元素。

範例

從「Background」一節將 @discoverable 新增至版本 5 的通訊協定的範例，在新版設計中看起來會像這樣：

@available(added=1, replaced=5)
protocol P {};

@available(added=5)
@discoverable
protocol P {};

另外，請考慮將包含成員的結構替換為匿名類型的結構體：

@available(added=1, replaced=2)
struct Foo {
    bar @generated_name("Bar") table {};
};

@available(added=2)
struct Foo {
    baz string;
};

由於第一個 Foo 標示為 replaced=2，因此 fidlc 會驗證另一個標示為 added=2 的 Foo。但「不會」對子項元素 bar 或匿名類型 Bar 執行類似的驗證。

實作

  1. 實作 replaced 引數，包括其驗證。

  2. 在適用情況下，將所有 FIDL 檔案變更為使用 replaced，而非 removed。

  3. 實作新的 removed 驗證。如果 (2) 缺少任何內容，CQ 就會失敗。

效能

這項提案成效不會影響成效。

人體工學

本提案直接支援該語言，讓「切換」模式更符合人體工學。

回溯相容性

本提案不會影響回溯相容性。

安全性考量

本提案對安全性沒有任何影響。

隱私權注意事項

這項提案對隱私權沒有任何影響。

測試

您必須更新以下檔案，才能測試新行為：

  • tools/fidl/fidlc/tests/availability_interleaving_tests.cc
  • tools/fidl/fidlc/tests/decomposition_tests.cc
  • tools/fidl/fidlc/tests/versioning_tests.cc
  • tools/fidl/fidlc/tests/versioning_types_tests.cc

說明文件

你必須更新以下網頁，才能建立文件 replaced 文件：

請移除「揮動」一詞，改用「已取代」一詞。

fidldoc 工具目前會在單一 API 級別的 JSON IR 上運作，因此永遠不會看見 removed 引數，也不會看到 replaced (https://fxbug.dev/42084086)。修正此問題後，應更新 fidldoc，以清楚指出內容何時取代而不是移除。

缺點、替代項目和未知

替代做法：重新加入引數

本提案推出了 replaced 引數，此引數可明確指出替換元素的時機，而非移除元素。這樣可避免以下情境：「我因為符合 removed=5 指定的條件，而且指定了 6，因此無法使用這個 API。」

我們可以同樣加入 re_added 引數，指出元素何時新增為取代項目 (而非第一次新增)。這樣可以避免以下狀況：「我覺得這個 API 顯示 added=6，我們指定 5，所以我還不能使用這個 API」。

我基於以下幾個原因拒絕這個替代方案：

  • 我認為第一個情境比第二種情境來得重要。

  • 「re_added」這個名字令人不滿意，我無法想一個更好的名稱。

  • 即使沒有這項工具，我們仍然可以讓 fidldoc 推斷元素是否為首次使用 added。

優先藝術與參考資料

我在 2021 年開發 FIDL 版本管理的期間討論了類似的想法，這個概念是在標題為「FIDL versioning: Swap element」的內部文件中。

本提案僅適用於 FIDL 版本管理的設計，因此目前為止沒有確切的問題。