在 Rust 中實作同步 FIDL 用戶端

必要條件

本教學課程假設您熟悉如何編寫及執行 Fuchsia 元件，以及如何實作 FIDL 伺服器，兩者皆在 FIDL 伺服器教學課程中提及。如需 FIDL 的完整教學課程，請參閱總覽。

總覽

本教學課程會實作 FIDL 通訊協定的用戶端，並根據上一個教學課程中建立的伺服器執行該通訊協定。本教學課程中的用戶端是同步的。我們也提供其他教學課程，可用於非同步用戶端。

如果您想自行編寫程式碼，請刪除下列目錄：

rm -r examples/fidl/rust/client_sync/*

建立元件

在 examples/fidl/rust/client_sync 中建立新的元件專案：

  1. 將 main() 函式新增至 examples/fidl/rust/client_sync/src/main.rs：

    fn main() {
  println!("Hello, world!");
}

  2. 在 examples/fidl/rust/client_sync/BUILD.gn 中為用戶端宣告目標：

    import("//build/components.gni")
import("//build/rust/rustc_binary.gni")


# Declare an executable for the client.
rustc_binary("bin") {
  name = "fidl_echo_rust_client_sync"
  edition = "2021"

  sources = [ "src/main.rs" ]
}

fuchsia_component("echo-client") {
  component_name = "echo_client"
  manifest = "meta/client.cml"
  deps = [ ":bin" ]
}

  3. 在 examples/fidl/rust/client_sync/meta/client.cml 中新增元件資訊清單：

    {
    include: [ "syslog/client.shard.cml" ],

    // Information about the program to run.
    program: {
        // Use the built-in ELF runner.
        runner: "elf",

        // The binary to run for this component.
        binary: "bin/fidl_echo_rust_client_sync",
    },

    // Capabilities used by this component.
    use: [
        { protocol: "fuchsia.examples.Echo" },
    ],
}

  4. 建立元件後，請確認您可以將其新增至建構設定：

    fx set core.x64 --with //examples/fidl/rust/client_sync:echo-client

  5. 建構 Fuchsia 映像檔：

    fx build

編輯 GN 依附元件

  1. 將下列依附元件新增至 rustc_binary：

      deps = [
    "//examples/fidl/fuchsia.examples:fuchsia.examples_rust",
    "//sdk/rust/zx",
    "//src/lib/fuchsia-component",
    "//third_party/rust_crates:anyhow",
  ]

  2. 然後在 main.rs 中匯入：

    use anyhow::{Context as _, Error};
use fidl_fuchsia_examples::{EchoEvent, EchoMarker};
use fuchsia_component::client::connect_to_protocol_sync;

伺服器教學課程會說明這些依附元件。

唯一的新依附元件是 fuchsia-zircon，這是一個 crate，其中包含用於建立 Zircon 核心系統呼叫的型別安全繫結。在本例中，crate 用於建立管道。

連線至伺服器

本節的步驟會說明如何在 main() 函式中新增程式碼，讓用戶端與伺服器連線並向其提出要求。

初始化管道

fn main() -> Result<(), Error> {
    // Connect to the Echo protocol, returning a synchronous proxy
    let echo =
        connect_to_protocol_sync::<EchoMarker>().context("Failed to connect to echo service")?;

    // Make an EchoString request, with no timeout for receiving the response
    let res = echo.echo_string("hello", zx::MonotonicInstant::INFINITE)?;
    println!("response: {:?}", res);

    // Make a SendString request
    echo.send_string("hi")?;
    // Wait for a single OnString event.
    let EchoEvent::OnString { response } =
        echo.wait_for_event(zx::MonotonicInstant::INFINITE).context("error receiving events")?;
    println!("Received OnString event for string {:?}", response);

    Ok(())
}

這個管道將用於用戶端與伺服器之間的通訊。

連線至伺服器

fn main() -> Result<(), Error> {
    // Connect to the Echo protocol, returning a synchronous proxy
    let echo =
        connect_to_protocol_sync::<EchoMarker>().context("Failed to connect to echo service")?;

    // Make an EchoString request, with no timeout for receiving the response
    let res = echo.echo_string("hello", zx::MonotonicInstant::INFINITE)?;
    println!("response: {:?}", res);

    // Make a SendString request
    echo.send_string("hi")?;
    // Wait for a single OnString event.
    let EchoEvent::OnString { response } =
        echo.wait_for_event(zx::MonotonicInstant::INFINITE).context("error receiving events")?;
    println!("Received OnString event for string {:?}", response);

    Ok(())
}

connect_channel_to_service 會將提供的管道端點繫結至指定的服務。實際上，這個呼叫會觸發一系列事件，這些事件會在用戶端開始，並追蹤先前教學課程中的伺服器程式碼：

  • 向元件架構提出要求，其中包含要連線的服務名稱和管道的另一端。系統會使用 EchoMarker 範本引數的 SERVICE_NAME 隱含取得服務名稱，這與在伺服器端決定服務路徑的方式類似。
  • 這個用戶端物件會從 connect_to_protocol 傳回。

在背景中，系統會將對元件架構的要求轉送至伺服器：

  • 在伺服器程序中收到這項要求時，系統會喚醒 async::Executor 執行器，並告知 ServiceFs 工作現在可以取得進度，且應執行。
  • ServiceFs 會喚醒、查看程序的啟動帳號內可用的要求，並透過呼叫 add_service、add_fidl_service 等方式，在 (service_name, service_startup_func) 清單中查詢要求的服務名稱。如果相符的 service_name 已存在，則會透過提供的管道呼叫 service_startup_func 來連線至新服務。
  • IncomingService::Echo 會使用 add_fidl_service 註冊的 Echo FIDL 通訊協定的 RequestStream (類型管道) 呼叫。傳入的要求管道會儲存在 IncomingService::Echo 中，並新增至傳入要求的串流。for_each_concurrent 會將 ServiceFs 消耗為 IncomingService 類型的 Stream。會為串流中的每個項目執行處理程序，該程序會比對傳入的要求，並將結果分派至 run_echo_server。當 ServiceFs 串流遭到 await 時，每個對 run_echo_server 的呼叫所產生的結果未來會並行執行。
  • 在管道上傳送要求時，Echo 服務可讀取管道，並在 run_echo_server 的主體中喚醒非同步程式碼。

將要求傳送至伺服器

程式碼會向伺服器發出兩項要求：

  • EchoString 要求
  • SendString 要求
fn main() -> Result<(), Error> {
    // Connect to the Echo protocol, returning a synchronous proxy
    let echo =
        connect_to_protocol_sync::<EchoMarker>().context("Failed to connect to echo service")?;

    // Make an EchoString request, with no timeout for receiving the response
    let res = echo.echo_string("hello", zx::MonotonicInstant::INFINITE)?;
    println!("response: {:?}", res);

    // Make a SendString request
    echo.send_string("hi")?;
    // Wait for a single OnString event.
    let EchoEvent::OnString { response } =
        echo.wait_for_event(zx::MonotonicInstant::INFINITE).context("error receiving events")?;
    println!("Received OnString event for string {:?}", response);

    Ok(())
}

從伺服器收到回應之前，對 echo_string 的呼叫都會遭到封鎖，因此必須使用逾時引數做為最後一個參數。

另一方面，對 send_string 的呼叫沒有逾時參數，因為 SendString 沒有回應。若是使用目前的伺服器實作，在收到這項要求後，會將 OnString 事件傳送至用戶端。不過，同步的 Rust 繫結不支援事件處理。

繫結參考資料說明這些方法的產生方式，Fuchsia rustdoc 包含所產生 FIDL Crate 的說明文件。

執行用戶端

為了讓用戶端和伺服器使用 Echo 通訊協定進行通訊，元件架構必須將 fuchsia.examples.Echo 能力從伺服器路由至用戶端。在本教學課程中，我們會使用

中探索領域元件的完整來源。

  1. 設定建構作業，加入提供的套件，其中包含回音領域、伺服器和用戶端：

    fx set core.x64 --with //examples/fidl/rust:echo-rust-client-sync

  2. 建構 Fuchsia 映像檔：

    fx build

  3. 執行 echo_realm 元件。這會建立用戶端和伺服器元件執行個體，並轉送功能：

    ffx component run /core/ffx-laboratory:echo_realm fuchsia-pkg://fuchsia.com/echo-rust-client-sync#meta/echo_realm.cm

  4. 啟動 echo_client 執行個體：

    ffx component start /core/ffx-laboratory:echo_realm/echo_client

伺服器元件會在用戶端嘗試連線至 Echo 通訊協定時啟動。您應該會在裝置記錄 (ffx log) 中看到類似以下的輸出內容：

[echo_server][][I] Listening for incoming connections...
[echo_server][][I] Received EchoString request for string "hello"
[echo_server][][I] Response sent successfully
[echo_client][][I] response: "hello"
[echo_server][][I] Received SendString request for string "hi"
[echo_server][][I] Event sent successfully
[echo_client][][I] Received OnString event for string "hi"

終止領域元件，停止執行並清理元件例項：

ffx component destroy /core/ffx-laboratory:echo_realm