fuchsia.component.runner

新增日期：7

通訊協定

ComponentController

定義於fuchsia.component.runner/component_runner.fidl

用於繫結及控管使用 ComponentRunner.Start() 啟動的元件執行個體的生命週期的通訊協定。元件管理員是此通訊協定預期的直接用戶端。

當受控制的元件執行個體因任何原因終止或無法存取時，伺服器會透過 Epitaph 關閉連線。

生命週期

元件可能有兩種狀態：Started 或 Stopped。在 ComponentRunner 關閉 ComponentController 控點前，元件會Started進入 ComponentRunner.Start()。接著，元件會轉換為 Stopped。

元件管理員會使用 ComponentController 以兩個步驟終止元件：

  1. 元件管理員會呼叫 Stop()，表示 ComponentRunner 應停止執行元件，並以填入方式關閉這項連線。
  2. 如果一段時間後 ComponentController 未關閉，元件管理員會呼叫 Kill() 表示 ComponentRunner 必須立即停止執行元件，再以動畫關閉這個連線。元件管理員在呼叫 Kill() 後，可能會等待一段時間再關閉 ComponentController 管道，但不保證會等待一段時間或多久。

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

在停止之前，元件可選擇使用 OnEscrow 在架構中儲存某些狀態，以便在下次啟動時再次接收這些狀態。

橫向

這個通訊協定會傳送 FIDL 參數，表示元件執行個體已終止。元件執行元件應在關閉連線之前先清除歸因於元件的所有資源。

伺服器可能會在發生錯誤時傳送下列憑證：

  • ZX_OK：已成功結束元件，通常是因為系統要求停止元件，或元件決定獨立結束。
  • INVALID_ARGUMENTS：
    • 這個執行元件不支援 start_info.resolved_url；
    • start_info 含有遺失或無效的引數。
  • INSTANCE_CANNOT_START：執行器無法啟動元件。舉例來說，無法找到或載入程式的重要部分，或是針對這個執行元件所參照的二進位檔無效。
  • RESOURCE_UNAVAILABLE：由於缺少資源，因此無法啟動元件。
  • INTERNAL：發生未預期的內部執行元件錯誤。
  • INSTANCE_DIED：已啟動元件執行個體，但隨後因發生錯誤而終止。
  • 其他狀態碼 (例如 ZX_ERR_PEER_CLOSED) 可能表示元件執行元件本身失敗。元件管理員可能會終止元件執行元件的工作來回應這類故障，以確保系統穩定性。

刪除

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

ComponentRunner 必須立即終止元件執行個體，然後以管道關閉這個連線。連線關閉後，元件管理員會將此元件執行個體視為停止，且元件的命名空間也會遭刪除。

在某些情況下，Kill() 可能會在 Stop() 之前發出，但不保證一定如此。

要求

<EMPTY>

OnEscrow

將部分元件的狀態儲存在架構中，以便在下次啟動時重新傳送至元件 (稱為「託管」的做法)。

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

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

透過 OnEscrow 託管的處理序一律會傳送至元件的下一個執行。

已新增：HEAD

回應

名稱類型
payload ComponentControllerOnEscrowRequest

OnPublishDiagnostics

讓執行者將診斷發布至平台的事件。

這個事件會向平台發出信號，說明此元件的執行元件正在發布元件執行階段的診斷資訊。元件管理員可選擇是否將這項資料提供給用戶端。

回應

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

停止

要求停止元件執行個體。

停止元件執行個體後，伺服器應使用 Epitaph 關閉這個連線。連線關閉後，元件管理員會將此元件執行個體視為停止，且元件的命名空間也會遭刪除。

要求

<EMPTY>

ComponentRunner

定義於fuchsia.component.runner/component_runner.fidl

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

這個通訊協定是由元件實作，其為其他元件提供執行階段環境。

注意：元件管理員是這個介面的唯一直接用戶端。

開始

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

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

錯誤會透過 ComponentController 通訊協定以階層方式傳送。如發生錯誤，執行元件必須確保已清除資源。

錯誤：

要求

名稱類型
start_info ComponentStartInfo
controller server_end<ComponentController>

資料表

ComponentControllerOnEscrowRequest 資源

定義於 fuchsia.component.runner/component_runner.fidl

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

提報傳出目錄伺服器端點。每當元件啟動時，架構都會透過 ComponentStartInfo.outgoing_dir 傳回這個管道。
escrowed_dictionary fuchsia.component.sandbox/Dictionary

託管部分使用者定義狀態。每當元件啟動時，架構會透過 ComponentStartInfo.escrowed_dictionary 傳回這些控制代碼。

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

範例

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

ComponentNamespaceEntry 資源

定義於fuchsia.component.runner/component_runner.fidl

單一元件命名空間項目，描述一個命名空間掛接點 (path) 及其背後的目錄 (directory)。此類型通常在向量內組成。詳情請參閱 ComponentStartInfo.ns。

序數欄位類型說明
path string[4095]

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

掛接在上述 path 的目錄。

ComponentStartInfo 資源

定義於fuchsia.component.runner/component_runner.fidl

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

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

元件的解析網址。

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

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

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

命名空間用於指定元件執行個體在啟動時接收的目錄組合。透過命名空間目錄，元件可能會存取可用的功能。命名空間的內容主要是由元件的 use 宣告決定，但也可能包含架構自動提供的額外功能。

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

  • "/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/Dictionary

這個字典含有資料，以及元件在先前執行期間透過 ComponentController.OnEscrow 提報的資料。

已新增：HEAD

業者

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