| RFC-0054：參數屬性 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 我們可以將屬性套用至 FIDL 的各種元素，但無法套用至參數。這個提案是擴充文法以接受參數屬性。 |
| 作者 | |
| 提交日期 (年/月) | 2019-11-21 |
| 審查日期 (年/月) | 2019-12-12 |
「A Chance to 編寫自行記錄 API 的機會」
摘要
我們可以將屬性套用至 FIDL 的各種元素，但無法套用至參數。這個提案是擴充文法以接受參數屬性。
與其他 RFC 的關係
這個 RFC 已由以下因素取代：
提振精神
只要具備更多語言元素的屬性，就能提升語言一致性，並於日後提供更多功能。任何無法在類型系統中編碼的 API 都可以改為在屬性中編碼。任何無法在類型系統中編碼的情況，只要利用屬性中的結構更詳細，就能簡化各種後端的後期驗證。這些屬性對於程式碼檢查和產生器也可以利用這項資訊產生更佳的程式碼，或套用至目標語言的屬性。這種做法有助於對譯文語言進行靜態和/或動態分析。此外，屬性很適合用來設計可能的擴充項目或類型系統的修正。
這項功能的驅動用途是檢查處理資料外洩情形、重複釋放和釋放後使用此功能。
核心 ABI (即系統呼叫) 也以 FIDL 格式表示，且帳號擁有權通常並不明確。使用者是否應該在 task_kill syscall 之後呼叫 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 Static 分析工具能夠擷取處理錯誤使用錯誤。
此原型已在 Fuchsia 中發現一些錯誤。
設計
這次提案是將參數屬性新增至 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 會產生效能成本，因此某些通訊協定 (例如 syscall) 應謹慎使用，或完全不使用。
先前的圖片和參考資料
Protobuf 針對訊息提供選項，這些選項的行為與參數屬性有點類似。FIDL 已經具有部分語言元素的屬性，例如成員和通訊協定。