RFC-0156：串流附加模式

RFC-0156：串流附加模式
狀態已接受
區域
  • 核心
說明

在串流中新增附加模式。
問題
Gerrit 變更
作者
審查人員
提交日期 (年-月-日)2022-04-06
審查日期 (年-月-日)2022-04-20

編輯此 RFC

編輯 RFC 中繼資料

摘要

這份 RFC 建議修改串流 API，方法是為串流新增附加模式，並從 zx_stream_writev 中移除附加選項。

提振精神

串流附加選項 ZX_STREAM_APPEND 目前僅用於 C++ VFS，用於為 memfs 實作 fuchsia.io/File.Write。所有 memfs 串流都會在 FIDL 連線的伺服器端運作，且連線的附加模式已知。在這種情況下，您可以存取附加模式，選擇性地將 ZX_STREAM_APPEND 傳遞至每個 zx_stream_writev 呼叫。

透過為使用者空間分頁器實作回寫功能，可將串流傳送至 FIDL 連線的用戶端，大幅提升 I/O 效能。使用目前的串流 API 將串流移至用戶端時，需要使用 fdio 追蹤連線的附加模式。

設計

總覽

這項設計的目標是避免在 fdio 中追蹤附加模式，並讓 stream API 更符合 POSIX。

串流 API 與 POSIX 中的讀取、寫入和搜尋檔案的操作非常相似，但附加內容的處理方式有所不同。在 POSIX 中，您可以將 O_APPEND 傳遞至 open，以附加模式開啟檔案。所有 POSIX write 對檔案的附加模式呼叫，其行為都與 zx_stream_writev 搭配 ZX_STREAM_APPEND 選項的行為類似。

在串流中新增附加模式可避免 fdio 儲存附加模式，並更符合 POSIX。有了這個新增功能，就不再需要 zx_stream_writev 的 ZX_STREAM_APPEND 選項。

API 變更

這份 RFC 包含 3 項 API 變更：

  1. 我們會為 zx_stream_create 新增名為 ZX_STREAM_MODE_APPEND 的新選項。使用 ZX_STREAM_MODE_APPEND 建立的串流會置於附加模式。所有以附加模式呼叫串流的 zx_stream_writev 都會以 ZX_STREAM_APPEND 傳遞至 zx_stream_writev 呼叫的行為運作。

  2. 系統會新增名為 ZX_PROP_STREAM_MODE_APPEND 的新屬性。這個屬性是 fdio 使用 F_SETFL 和 O_APPEND 實作 fcntl 時所需的屬性。

    • ZX_PROP_STREAM_MODE_APPEND 的值類型為 uint8_t。
    • 使用 ZX_PROP_STREAM_MODE_APPEND 和 0 值呼叫 zx_object_set_property，會將資料流從附加模式中移除。
    • 使用 ZX_PROP_STREAM_MODE_APPEND 和 0 以外的任何值呼叫 zx_object_set_property，會將資料流置於附加模式。
    • 如果 zx_object_get_property 呼叫含有 ZX_PROP_STREAM_MODE_APPEND，則如果串流處於附加模式，屬性值會是 1；如果串流未處於附加模式，則屬性值會是 0。

  3. zx_stream_writev 的 ZX_STREAM_APPEND 選項將會移除。

實作

這份 RFC 將在 3 項 Gerrit 變更中實作：

  1. 將 ZX_STREAM_MODE_APPEND 和 ZX_PROP_STREAM_MODE_APPEND 新增至串流 API。

  2. 將 C++ VFS 從 ZX_STREAM_APPEND 遷移至 ZX_STREAM_MODE_APPEND 和 ZX_PROP_STREAM_MODE_APPEND

  3. 從串流 API 中移除 ZX_STREAM_APPEND 選項。

成效

這項提案對成效應該不會造成任何影響。

人體工學

在串流中儲存附加模式會讓串流 API 與開發人員熟悉的 fuchsia.io/Directory.Open 和 open 保持一致。

安全性考量

無。

隱私權注意事項

無。

測試

我們會編寫核心測試，以便測試新的 API，包括多執行緒的測試。

memfs 使用的現有 fs_test 套件已包含附加相關的測試，應可在遷移期間找出任何潛在的回歸現象。

說明文件

我們會根據 API 的變更更新 Zircon 串流說明文件。

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

替代做法：在 fdio 中儲存附加模式

直接將連線的附加模式儲存在 fdio 中，並使用原始的串流 API。

建議在串流中儲存附加模式，因為這與 POSIX 中的附加功能運作方式相符。

替代做法：保留 ZX_STREAM_APPEND 以供 zx_stream_writev 使用

支援串流的檔案系統通常會透過將要求分派至串流內部的方式，實作 fuchsia.io/File.Read、Write 和 Seek。每個連線都會追蹤其附加模式，以便回應 GetFlags 要求，因此可方便您將 ZX_STREAM_APPEND 與 zx_stream_writev 搭配使用。

移除 ZX_STREAM_APPEND 會強制檔案系統保持連線的附加模式和串流的附加模式同步，這並不困難。建議您減少 API 介面面積並符合 POSIX，而非保留 ZX_STREAM_APPEND。

既有技術與參考資料

zx_stream_create 搭配 ZX_STREAM_MODE_APPEND 的用法，類似於 open 搭配 POSIX 的 O_APPEND。

zx_object_set_property 搭配 ZX_PROP_STREAM_MODE_APPEND 的情況，類似於 fcntl 搭配 POSIX 的 F_SETFL 和 O_APPEND。