fuchsia.component.runner

新增：7

通訊協定

ComponentController

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

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

當受控元件執行個體終止或因任何原因而無法存取時，伺服器會關閉連線並傳送墓誌銘。

生命週期

元件可能處於 Started 或 Stopped 狀態。從呼叫 ComponentRunner.Start() 到 ComponentRunner 關閉 ComponentController 控制代碼，元件會處於 Started 狀態。接著，元件會轉換為 Stopped。

元件管理服務會使用 ComponentController，透過兩個步驟終止元件：

  1. 元件管理服務會呼叫 Stop()，表示 ComponentRunner 應停止元件的執行作業，並傳送 OnStop 事件。
  2. 如果 ComponentController 在一段時間後未關閉，元件管理服務會呼叫 Kill()，指出 ComponentRunner 必須立即停止元件的執行作業，然後傳送 OnStop 事件。元件管理服務可能會在呼叫 Kill() 後等待一段時間，再傳送 OnStop，但不保證會等待或等待多久。

元件管理服務會先等待 ComponentController 關閉，然後刪除為已停止元件託管的命名空間。元件管理服務可能會呼叫 Kill()，而不先呼叫 Stop()。

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

元件停止時，執行元件應傳送 OnStop 事件，而非直接關閉管道，以回報元件的終止狀態 (請見下方說明) 和結束代碼 (選用)。執行元件傳送 OnStop 後，即可關閉 [ComponentRunner]；元件架構收到這個事件時，會關閉其管道端。

舊版

除了傳送 OnStop 之外，執行元件也可以關閉管道，並將墓誌銘設為終止狀態，但這是為了回溯相容性而採用的舊版方法，不建議使用。

終止狀態

終止狀態表示執行元件對元件的最終處置。

請注意，終止狀態不等同於元件的結束代碼。元件的結束代碼是代表程式本身傳回代碼的整數，執行元件可選擇是否回報。舉例來說，如果是 ELF 元件，則為 main() 傳回的值。終止狀態是執行工具針對元件終止的狀態碼，可能會擷取在執行元件本身 (而非程式) 的內容中發生的失敗模式。

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

  • 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

執行器將診斷資訊發布至平台的事件。

這個事件會向平台發出信號，表示這個元件的執行元件正在發布元件執行階段的診斷資訊。元件管理服務可選擇向用戶端公開這項資料。

新增：27

回應

名稱類型
payload ComponentDiagnostics

OnStop

回報元件已停止，並提供終止相關資料。這會導致元件轉換生命週期至 Stopped。

執行元件傳送 OnStop 後，即可關閉這個 [ComponentRunner]；元件架構收到這個事件時，會關閉其管道端。

或者，執行元件可能會關閉控制器管道，而不使用此事件來表示元件停止，但此方法已過時，不再建議使用。

新增：HEAD

回應

名稱類型
payload ComponentStopInfo

停止

要求停止元件執行個體。

停止元件執行個體後，伺服器應關閉此連線並傳送 epitaph。連線關閉後，元件管理服務會將這個元件執行個體視為已停止，並會拆除元件的命名空間。

要求

<EMPTY>

ComponentRunner

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

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

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

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

開始

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

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

錯誤會透過 ComponentController 通訊協定以墓誌銘的形式傳送。如果發生錯誤，執行元件必須確保資源已清理。

要求

名稱類型
start_info ComponentStartInfo
controller server_end:ComponentController

TaskProvider

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

由想要透過執行階段目錄提供 Zircon 工作的執行器提供。

新增：HEAD

GetJob

傳回所要求元件的工作控制代碼。

如果成功，則會傳回與執行元件權限相同的控制代碼。

要求

<EMPTY>

回應

名稱類型
payload TaskProvider_GetJob_Result

STRUCTS

TaskProvider_GetJob_Response 資源

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

欄位類型說明預設
job handle<job> 無預設值

TABLES

ComponentControllerOnEscrowRequest 資源

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

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

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

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

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

範例

假設某個元件需要託管一組事件，代表某項耗費大量資源的計算結果。它可以建立字典，將事件配對放入適當的鍵 (例如 "my_event_pair")，然後在啟動時檢查該項目。請注意，這項功能已淘汰，請改用 escrowed_dictionary_handle。
escrowed_dictionary_handle handle<eventpair>

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

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

範例

假設某個元件需要託管一組事件，代表某項耗費大量資源的計算結果。它可以建立字典，將事件組合放入適當的鍵 (例如 "my_event_pair")，然後在啟動時檢查該項目。
recoverable_bytes uint64

這個元件停止執行時可復原的位元組。用於追蹤元件託管時節省的記憶體量，僅供開發用途。

ComponentDiagnostics 資源

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

新增：27

序數欄位類型說明
tasks ComponentTasks

ComponentNamespaceEntry 資源

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

單一元件命名空間項目，用於描述命名空間掛接點 (path) 和支援該掛接點的目錄 (directory)。這種類型通常會在向量中組成。詳情請參閱 ComponentStartInfo.ns。

序數欄位類型說明
path string:4095

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

掛接在上述 path 的目錄。

ComponentStartInfo 資源

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

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

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

元件的網址。基於歷史原因，稱為 resolved_url，而非 url。
program fuchsia.data/Dictionary

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

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

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

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

  • 「/svc」：這個目錄包含元件透過「import」宣告要求使用的服務。
  • 「/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 信號，才會在元件中建立程序。此外，他們也會確保在等待這個 eventpair 之前，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 執行時，託管的資料和控制代碼。請注意，這個欄位已淘汰，請改用 escrowed_dictionary_handle。

新增：HEAD
escrowed_dictionary_handle handle<eventpair>

字典，內容包含元件先前透過 ComponentController.OnEscrow 執行時託管的資料和控制代碼。

新增：HEAD

ComponentStopInfo 資源

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

序數欄位類型說明
termination_status zx/Result

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

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

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

執行器實作者可將執行階段專屬的結束代碼概念 (例如 libc 結束狀態) 對應至這個欄位。或選擇留空。

ComponentTasks 資源

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

新增：27

序數欄位類型說明
component_task Task
parent_task Task

UNIONS

工作彈性 資源

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

新增：27
序數Variant類型說明
job handle<job>
process handle<process>
thread handle<thread>

TaskProvider_GetJob_Result strict resource

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

序數Variant類型說明
response TaskProvider_GetJob_Response
err zx/Status

常數

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