fuchsia.component.runner

新增：7

PROTOCOLS

ComponentController

在 fuchsia.component.runner/component_runner.fidl 中定義的

用於繫結及控制元件執行個體生命週期的通訊協定 開始使用 ComponentRunner.Start()元件管理工具就是 此通訊協定的目標直接用戶端。

當控制的元件執行個體終止或無法存取時 伺服器會因為任何理由關閉連線，並顯示憑證終止服務。

生命週期

元件可能處於以下其中一種狀態：Started 或 Stopped。 從呼叫 ComponentRunner.Start() 時，元件為 Started 直到 ComponentRunner 關閉 ComponentController 控點 然後轉換至 Stopped

元件管理員使用 ComponentController 將元件終止 步驟：

  1. 元件管理員呼叫 Stop() 以表示 ComponentRunner 應該停止執行元件的執行作業，並傳送 OnStop 事件。
  2. 如果經過一段時間後 ComponentController 未關閉，元件 管理員呼叫 Kill()，表示 ComponentRunner 必須暫停 元件執行後，然後傳送 OnStop 事件。 元件管理員呼叫 Kill() 後，可能會等待一段時間 然後再傳送 OnStop，但無法保證它會等待或多久。

元件管理員會先等待 ComponentController 關閉， 然後拆解為停止元件所代管的命名空間元件 管理員不必先呼叫 Stop()，即可呼叫 Kill()。

停止之前，元件可以視需要使用 OnEscrow 來儲存 物件狀態，並在下次擷取時再次接收這些狀態 已開始。

元件停止後，執行元件應傳送 OnStop 事件 回報元件的終止狀態，而非只是關閉管道。 (參閱下文) 和結束代碼 (選擇性)。執行元件傳送 OnStop 後 可以自由關閉 [ComponentRunner]這個元件架構會關閉 透過整個管道發布此活動

舊版

非傳送 OnStop 也合法讓執行元件關閉管道 其口號等於終止狀態，但這是舊版做法 以提供系統不再建議使用的回溯相容性

終止狀態

終止狀態代表該元件在 執行元件

請注意，終止狀態「不」與元件的結束代碼相同。 元件的結束程式碼 (執行元件可選用) 是 整數，代表程式本身的傳回代碼。例如 ELF 則是 main() 傳回的值。終止狀態為 元件終止期間的 runner 狀態碼， 而不是發生在執行元件本身的故障模式時 計畫。

伺服器可能會在發生錯誤時傳送下列終止狀態：

  • ZX_OK：成功離開元件，原因通常是 元件被要求停止或自行決定退出
  • INVALID_ARGUMENTS：
    • 這個項目不支援 start_info.resolved_url 執行元件；
    • start_info 包含遺漏或無效的引數。
  • INSTANCE_CANNOT_START：執行器無法啟動元件。 例如，在程式中找不到某個關鍵部分，或是 或是參照的二進位檔不適用於此執行元件。
  • RESOURCE_UNAVAILABLE：無法啟動元件，原因如下： 缺乏資源
  • INTERNAL：發生未預期的內部執行元件錯誤。
  • INSTANCE_DIED：元件執行個體已啟動，但 但因發生錯誤而終止
  • 其他狀態碼 (例如 ZX_ERR_PEER_CLOSED) 可能表示驗證失敗 加入元件執行元件本身的設定而元件管理員可能會提供 終止元件執行元件的工作，確保系統發生錯誤 穩定性。

刪除

立即停止這個元件執行個體。

ComponentRunner 必須立即終止元件執行個體，並 然後用 Epitai 關閉這個連線連線後 因此元件管理員會將這個元件執行個體視為 已停止，元件的命名空間將一併移除。

在某些情況下，Kll() 可能會在 Stop() 之前發出，但沒有 保證。

要求

<空白>

OnEscrow

將元件的部分狀態儲存在架構中，以便重新提交 下次啟動元件時就會加入元件 (這個做法稱為 「託管」)。

架構收到此事件後，會等待目前的 元件執行作業已完成，然後再次啟動元件 系統在 outgoing_dir 上觀察到ZX_CHANNEL_READABLE信號時。

重複呼叫會取代舊託管的值。我們不建議這麼做。

透過 OnEscrow 託管的控制代碼一律會傳送至下一個 這個元件的執行作業

新增時間：HEAD

回應

名稱類型
payload ComponentControllerOnEscrowRequest

OnPublishDiagnostics

用於將診斷發布至平台的事件。

此事件向平台發出信號，表示此 發布診斷元件的 元件。元件管理員可選擇是否公開這項資料 。

回應

名稱類型
payload fuchsia.diagnostics.types/ComponentDiagnostics

OnStop

回報元件已停止，並提供終止相關資料。這將 促使元件將生命週期轉換為 Stopped。

執行元件傳送 OnStop 後，即可直接關閉此 [ComponentRunner]；這個 元件架構會在收到這個事件時關閉管道的結尾

執行元件也可以在沒有這個事件的情況下關閉控制器管道，藉此發出訊號 元件停止，但此方法屬於舊版，因此不建議使用。

新增時間：HEAD

回應

名稱類型
payload ComponentStopInfo

停止

要求停止元件執行個體。

停止元件執行個體後，伺服器應關閉此 經適當語境簽署連線後 因此元件管理員會將這個元件執行個體視為 已停止，元件的命名空間將一併移除。

要求

<空白>

ComponentRunner

在 fuchsia.component.runner/component_runner.fidl 中定義的

用於執行元件的通訊協定。

這項通訊協定是由提供執行階段的元件實作 環境其他元件

注意：元件管理員是元件管理員 存取 API

開始

開始執行 start_info 描述的元件執行個體。

元件管理員會繫結，並使用 controller 控制 都會在新啟動元件執行個體的生命週期內

錯誤會以 A 符號的形式在 ComponentController 上傳送 因此效能相當卓越發生錯誤時，執行元件必須確保 清理資源

要求

名稱類型
start_info ComponentStartInfo
controller server_end<ComponentController>

資料表

ComponentControllerOnEscrowRequest 資源

在 fuchsia.component.runner/component_runner.fidl 中定義的

Ordinal欄位類型說明
outgoing_dir server_end<fuchsia.io/Directory>

收合傳出目錄伺服器端點。每當 組成元件後，架構就會透過 ComponentStartInfo.outgoing_dir.
escrowed_dictionary fuchsia.component.sandbox/DictionaryRef

託管使用者定義的狀態。每次啟動元件時 架構就會透過 ComponentStartInfo.escrowed_dictionary.

架構不會等待這些物件的任何信號。

範例

假設元件需要託管一個代表事件的 一些昂貴的計算結果可建立 字典，將事件組合放入適當的鍵中 (例如 "my_event_pair")，然後在啟動時檢查該項目。

ComponentNamespaceEntry 資源

在 fuchsia.component.runner/component_runner.fidl 中定義的

單一元件命名空間項目，用於說明命名空間掛接點 (path) 和支援該資料的目錄 (directory)。這個類型通常 組成詳情請參閱 ComponentStartInfo.ns。

Ordinal欄位類型說明
path string[4095]

目錄的掛接點，包括 開頭加上斜線例如：「/pkg」、「/svc」或「/config/data」。
directory fuchsia.io/Directory

掛接在上述 path 的目錄。

ComponentStartInfo 資源

在 fuchsia.component.runner/component_runner.fidl 中定義的

用於啟動新元件執行個體的參數。

Ordinal欄位類型說明
resolved_url fuchsia.url/Url

元件的已解析網址。

這是由元件解析器取得的標準網址 追蹤並解析相對路徑。
program fuchsia.data/Dictionary

元件的程式宣告。 這項資訊來自 ComponentDecl.program。
ns vector<ComponentNamespaceEntry>[32]

提供給元件執行個體的命名空間。

命名空間會指定一組目錄，其中有一組元件執行個體 才會在啟動時接收。透過命名空間目錄 可存取可用的功能。命名空間的內容 主要取決於元件的 use 宣告 也包含由 Pod 手動 這個架構的重點在於

按照慣例，元件的命名空間通常包含部分或全部 下列目錄：

  • "/svc"：包含所需元件服務的目錄 透過應用程式的「匯入」工具使用宣告的內容
  • "/pkg"：內含元件套件的目錄，包括 二進位檔、程式庫和其他資產

每個項目中指定的掛接點均不得重複，且 確保不會重疊舉例來說，[{"/foo", ..}, {"/foo/bar", ..}] 是 無效。
outgoing_dir server_end<fuchsia.io/Directory>

此元件提供的目錄。
runtime_dir server_end<fuchsia.io/Directory>

執行元件提供的目錄，用於顯示 這個元件跑者必須放送或放下，以免 無限期封鎖任何消費者
numbered_handles vector<fuchsia.process/HandleInfo>[128]

傳遞至元件的編號控點。

如果元件不支援編號控點，執行元件應該是執行器 來關閉控點。
encoded_config fuchsia.mem/Data

元件設定的二進位表示法。

版面配置

資料的前 2 個位元組應解讀為無正負號 16 位元 小端序整數，代表之後的位元組數 當中包含設定總和檢查碼在總和檢查碼之後 個位元組是頂層結構體的持續 FIDL 訊息。結構體 欄位符合元件已編譯資訊清單的設定欄位 順序相同
break_on_start handle<eventpair>

偵錯工具可用來延後元件啟動事件的事件。

舉例來說，ELF 執行器會阻止在元件中建立程序 直到 ZX_EVENTPAIR_PEER_CLOSED 收到此事件配對訊號為止。其他 確保在等待此事件組合之前，已執行 Runtime_dir。 ELF 偵錯工具可以查詢 runtime_dir，以判斷是否要附加於 他們會丟棄事件配對的另一端，並在 fuchsia.component.events 中的 DebugStarted 事件。
component_instance handle<event>

代表元件執行個體的不透明權杖。

fuchsia.component/Introspector 通訊協定可用於取得 此憑證中執行個體的字串路徑名稱。

執行器可能會將此權杖發布為診斷資訊的一部分， 不瞭解執行中的元件

元件執行個體刪除時，權杖就會失效。

新增時間：HEAD
escrowed_dictionary fuchsia.component.sandbox/DictionaryRef

字典，內含元件已託管的資料和處理代碼 仍可透過 ComponentController.OnEscrow 執行這個回呼。

新增時間：HEAD

ComponentStopInfo 資源

在 fuchsia.component.runner/component_runner.fidl 中定義的

Ordinal欄位類型說明
termination_status zx/Status

元件的終止狀態，如上方 [ComponentRunner] 所述。

呼叫端應設定這個欄位。如果沒有，架構會假設 值為 ZX_OK。
exit_code int64

(選用) 元件執行個體的結束代碼。

執行器實作項目可以對應執行階段專屬的結束程式碼概念 (例如 libc 結束狀態)。或者，他們可能會選擇 將此欄位留白

觀測站

名稱值類型說明
MAX_HANDLE_COUNT 128 uint32
MAX_NAMESPACE_COUNT 32 uint32