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

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

在 @available 屬性中新增 replaced=N 引數
問題
Gerrit 變更
作者
審查人員
提交日期 (年-月-日)2023-09-26
審查日期 (年-月-日)2023 年 10 月 24 日

編輯此 RFC

編輯 RFC 中繼資料

摘要

變更 FIDL 的 @available 屬性，以支援 replaced 引數。它與 removed 類似，但會驗證替換項目是否為相同版本的 added。

背景

RFC-0083：FIDL 版本管理引入了 @available 屬性，用於管理 FIDL API 的版本。該設計的一項要求，是允許為所有可能的變更建立版本。換句話說，在單一 versioned.fidl 檔案中，應可表示 v1.fidl 轉換為任意不同的 v2.fidl。這項設計滿足這項需求，只要版本範圍不重疊，就允許多個元素使用相同的名稱。

舉例來說，您可以考慮在第 5 版中，將 @discoverable 屬性新增至通訊協定 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其他同名元素標示為 added=N。

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

範例

背景一節中，在第 5 版的通訊協定中加入 @discoverable 的範例，在新設計中會如下所示：

@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 文件：

您也應移除「swapping」一詞，改用「replaced」。

fidldoc 工具目前會針對單一 API 級別運作 JSON IR，因此不會看到 removed 引數，也不會看到 replaced (https://fxbug.dev/42084086)。修正後，fidldoc 應更新，以便清楚指出何時會取代而非移除某些項目。

缺點、替代方案和未知事項

替代方案：重新加入的引數

此提案引入 replaced 引數，可清楚指出元素何時會取代而非移除。這可避免發生以下情況：「我以為我無法使用這個 API，因為它顯示 removed=5，而我們指定的是 6。」

我們也可以以類似的方式引入 re_added 引數，以便說明何時新增元素做為替換，而非首次新增。這麼做可避免發生「我以為我還不能使用這個 API，因為它顯示 added=6，而我們指定的目標是 5」的情況。

我拒絕這個替代方案的原因如下：

  • 我認為第一種情況比第二種情況更重要。

  • re_added 這個名稱不太理想，但我找不到更好的名稱。

  • 即使沒有這項資訊，我們還是可以讓 fidldoc 推斷元素是否是第一次 added。

既有技術與參考資料

我在 2021 年開發 FIDL 版本時，曾在標題為「FIDL 版本：交換元素」的內部文件中討論過類似的想法。

這個提案非常明確地針對 FIDL 版本設計，因此就我所知，這個問題並沒有先前技術。