C++ 中的协议请求管道

前提条件

本教程基于 C++ 使用入门教程。

概览

在 Fuchsia 上使用 FIDL 的一个常见方面是在协议之间传递协议端点。许多 FIDL 消息都包含通道的客户端或服务器端，其中通道用于通过不同的 FIDL 协议进行通信。在这种情况下，客户端允许向指定协议发出请求，而服务器端必须实现指定协议。客户端结束和服务器结束的另一组术语是协议和协议请求。

本教程涵盖以下内容：

  • 这些客户端和服务器的用法在 FIDL 和 C++ FIDL 绑定中均已结束。
  • 协议请求流水线模式及其优势。

本教程的完整示例代码位于 //examples/fidl/cpp/request_pipelining。

FIDL 协议

本教程实现了 fuchsia.examples 库中的 EchoLauncher 协议：

@discoverable
closed protocol EchoLauncher {
    strict GetEcho(struct {
        echo_prefix string:MAX_STRING_LENGTH;
    }) -> (resource struct {
        response client_end:Echo;
    });
    strict GetEchoPipelined(resource struct {
        echo_prefix string:MAX_STRING_LENGTH;
        request server_end:Echo;
    });
};

此协议可让客户端检索 Echo 协议的实例。客户端可以指定一个前缀，生成的 Echo 实例会将该前缀添加到每个响应中。

您可以使用以下两种方法来完成此操作：

  • GetEcho：将前缀作为请求，并使用连接到 Echo 协议实现的通道的客户端端点进行响应。在收到响应中的客户端端点后，客户端可以使用该客户端端点开始通过 Echo 协议发出请求。
  • GetEchoPipelined：将渠道的服务器端作为请求参数之一，并将 Echo 的实现绑定到该参数。发出请求的客户端应已持有客户端端，并且会在调用 GetEchoPipelined 后开始在该渠道上发出 Echo 请求。

顾名思义，后者使用一种称为协议请求流水线的模式，是首选方法。本教程将实现这两种方法。

实现服务器

实现 Echo 协议

此 Echo 实现允许指定前缀，以便区分 Echo 服务器的不同实例：

// Implementation of the Echo protocol that prepends a prefix to every response.
class EchoImpl final : public fidl::Server<fuchsia_examples::Echo> {
 public:
  explicit EchoImpl(std::string prefix) : prefix_(prefix) {}
  // This method is not used in the request pipelining example, so requests are ignored.
  void SendString(SendStringRequest& request, SendStringCompleter::Sync& completer) override {}

  void EchoString(EchoStringRequest& request, EchoStringCompleter::Sync& completer) override {
    FX_LOGS(INFO) << "Got echo request for prefix " << prefix_;
    completer.Reply(prefix_ + request.value());
  }

  const std::string prefix_;
};

由于客户端仅使用 EchoString，因此 SendString 处理程序为空。

实现 EchoLauncher 协议

// Implementation of EchoLauncher. Each method creates an instance of EchoImpl
// with the specified prefix.
class EchoLauncherImpl final : public fidl::Server<fuchsia_examples::EchoLauncher> {
 public:
  explicit EchoLauncherImpl(async_dispatcher_t* dispatcher) : dispatcher_(dispatcher) {}

  void GetEcho(GetEchoRequest& request, GetEchoCompleter::Sync& completer) override {
    FX_LOGS(INFO) << "Got non-pipelined request";
    auto [client_end, server_end] = fidl::Endpoints<fuchsia_examples::Echo>::Create();
    fidl::BindServer(dispatcher_, std::move(server_end),
                     std::make_unique<EchoImpl>(request.echo_prefix()));
    completer.Reply(std::move(client_end));
  }

  void GetEchoPipelined(GetEchoPipelinedRequest& request,
                        GetEchoPipelinedCompleter::Sync& completer) override {
    FX_LOGS(INFO) << "Got pipelined request";
    fidl::BindServer(dispatcher_, std::move(request.request()),
                     std::make_unique<EchoImpl>(request.echo_prefix()));
  }

  async_dispatcher_t* dispatcher_;
};

对于 GetEcho，代码首先需要实例化通道的两端。然后，它使用服务器端启动 Echo 实例，再通过客户端发送响应。对于 GetEchoPipelined，客户端已完成创建渠道两端的工作。它保留了一端，并将另一端传递给服务器，因此所有代码需要做的就是将服务器端绑定到新的 EchoImpl。

提供 EchoLauncher 协议

主循环与服务器教程中的相同，但提供的是 EchoLauncher 而不是 Echo。

int main(int argc, char** argv) {
  async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
  async_dispatcher_t* dispatcher = loop.dispatcher();

  component::OutgoingDirectory outgoing = component::OutgoingDirectory(dispatcher);
  zx::result result = outgoing.ServeFromStartupInfo();
  if (result.is_error()) {
    FX_LOGS(ERROR) << "Failed to serve outgoing directory: " << result.status_string();
    return -1;
  }

  result = outgoing.AddUnmanagedProtocol<fuchsia_examples::EchoLauncher>(
      [dispatcher](fidl::ServerEnd<fuchsia_examples::EchoLauncher> server_end) {
        FX_LOGS(INFO) << "Incoming connection for "
                      << fidl::DiscoverableProtocolName<fuchsia_examples::EchoLauncher>;
        fidl::BindServer(dispatcher, std::move(server_end),
                         std::make_unique<EchoLauncherImpl>(dispatcher));
      });
  if (result.is_error()) {
    FX_LOGS(ERROR) << "Failed to add EchoLauncher protocol: " << result.status_string();
    return -1;
  }

  FX_LOGS(INFO) << "Running echo launcher server" << std::endl;
  loop.Run();
  return 0;
}

构建服务器

（可选）如需检查是否一切正常，请尝试构建服务器：

  1. 配置 GN build 以包含服务器：

    fx set core.x64 --with //examples/fidl/cpp/request_pipelining/server:echo-server

  2. 构建 Fuchsia 映像：

    fx build

实现客户端

连接到 EchoLauncher 服务器后，客户端代码使用 GetEcho 连接到 Echo 的一个实例，使用 GetEchoPipelined 连接到另一个实例，然后对每个实例发出 EchoString 请求。

非流水线式客户端

这是非流水线代码：

int main(int argc, const char** argv) {
  async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
  async_dispatcher_t* dispatcher = loop.dispatcher();
  int num_responses = 0;

  // Connect to the EchoLauncher protocol
  zx::result launcher_client_end = component::Connect<fuchsia_examples::EchoLauncher>();
  ZX_ASSERT(launcher_client_end.is_ok());
  fidl::Client launcher(std::move(*launcher_client_end), dispatcher);

  // Make a non-pipelined request to get an instance of Echo
  launcher->GetEcho({"non pipelined: "})
      .ThenExactlyOnce([&](fidl::Result<fuchsia_examples::EchoLauncher::GetEcho>& result) {
        ZX_ASSERT(result.is_ok());
        // Take the Echo client end in the response, bind it to another client, and
        // make an EchoString request on it.
        fidl::SharedClient echo(std::move(result->response()), dispatcher);
        echo->EchoString({"hello!"})
            .ThenExactlyOnce(
                // Clone |echo| into the callback so that the client
                // is only destroyed after we receive the response.
                [&, echo = echo.Clone()](fidl::Result<fuchsia_examples::Echo::EchoString>& result) {
                  ZX_ASSERT(result.is_ok());
                  FX_LOGS(INFO) << "Got echo response " << result->response();
                  if (++num_responses == 2) {
                    loop.Quit();
                  }
                });
      });

  auto [client_end, server_end] = fidl::Endpoints<fuchsia_examples::Echo>::Create();
  // Make a pipelined request to get an instance of Echo
  ZX_ASSERT(launcher->GetEchoPipelined({"pipelined: ", std::move(server_end)}).is_ok());
  // A client can be initialized using the client end without waiting for a response
  fidl::Client echo_pipelined(std::move(client_end), dispatcher);
  echo_pipelined->EchoString({"hello!"})
      .ThenExactlyOnce([&](fidl::Result<fuchsia_examples::Echo::EchoString>& result) {
        ZX_ASSERT(result.is_ok());
        FX_LOGS(INFO) << "Got echo response " << result->response();
        if (++num_responses == 2) {
          loop.Quit();
        }
      });

  loop.Run();
  return num_responses == 2 ? 0 : 1;
}

此代码有两层回调：

  • 外层处理启动器 GetEcho 响应。
  • 内部层处理 EchoString 响应。

在 GetEcho 响应回调中，代码将返回的客户端端点绑定到 fidl::SharedClient<Echo>，并将克隆放置到 EchoString 回调中，以便将客户端的生命周期延长到收到回显响应时，这很可能是在顶级回调返回之后。

流水线式客户端

尽管必须先创建一对端点，但流水线式代码要简单得多：

int main(int argc, const char** argv) {
  async::Loop loop(&kAsyncLoopConfigNeverAttachToThread);
  async_dispatcher_t* dispatcher = loop.dispatcher();
  int num_responses = 0;

  // Connect to the EchoLauncher protocol
  zx::result launcher_client_end = component::Connect<fuchsia_examples::EchoLauncher>();
  ZX_ASSERT(launcher_client_end.is_ok());
  fidl::Client launcher(std::move(*launcher_client_end), dispatcher);

  // Make a non-pipelined request to get an instance of Echo
  launcher->GetEcho({"non pipelined: "})
      .ThenExactlyOnce([&](fidl::Result<fuchsia_examples::EchoLauncher::GetEcho>& result) {
        ZX_ASSERT(result.is_ok());
        // Take the Echo client end in the response, bind it to another client, and
        // make an EchoString request on it.
        fidl::SharedClient echo(std::move(result->response()), dispatcher);
        echo->EchoString({"hello!"})
            .ThenExactlyOnce(
                // Clone |echo| into the callback so that the client
                // is only destroyed after we receive the response.
                [&, echo = echo.Clone()](fidl::Result<fuchsia_examples::Echo::EchoString>& result) {
                  ZX_ASSERT(result.is_ok());
                  FX_LOGS(INFO) << "Got echo response " << result->response();
                  if (++num_responses == 2) {
                    loop.Quit();
                  }
                });
      });

  auto [client_end, server_end] = fidl::Endpoints<fuchsia_examples::Echo>::Create();
  // Make a pipelined request to get an instance of Echo
  ZX_ASSERT(launcher->GetEchoPipelined({"pipelined: ", std::move(server_end)}).is_ok());
  // A client can be initialized using the client end without waiting for a response
  fidl::Client echo_pipelined(std::move(client_end), dispatcher);
  echo_pipelined->EchoString({"hello!"})
      .ThenExactlyOnce([&](fidl::Result<fuchsia_examples::Echo::EchoString>& result) {
        ZX_ASSERT(result.is_ok());
        FX_LOGS(INFO) << "Got echo response " << result->response();
        if (++num_responses == 2) {
          loop.Quit();
        }
      });

  loop.Run();
  return num_responses == 2 ? 0 : 1;
}

与客户端教程不同，异步循环运行一次即完成，同时运行非流水线代码和流水线代码，以便观察操作顺序。客户端会跟踪接收到的响应数量，以便在不再需要接收服务器发送的消息时退出循环。

构建客户端

（可选）如需检查是否正确，请尝试构建客户端：

  1. 配置 GN build 以包含服务器：

    fx set core.x64 --with //examples/fidl/cpp/request_pipelining/client:echo-client

  2. 构建 Fuchsia 映像：

    fx build

运行示例代码

本教程提供了一个 组件，用于为 fuchsia.examples.Echo 和 fuchsia.examples.EchoLauncher 声明相应的功能和路由。

中探索 realm 组件的完整源代码

  1. 配置 build 以包含提供的软件包，该软件包包含回显 realm、服务器和客户端：

    fx set core.x64 --with //examples/fidl/cpp/request_pipelining

  2. 构建 Fuchsia 映像：

    fx build

  3. 运行 echo_realm 组件。这会创建客户端和服务器组件实例，并路由功能：

    ffx component run /core/ffx-laboratory:echo_realm fuchsia-pkg://fuchsia.com/echo-launcher-cpp#meta/echo_realm.cm

  4. 启动 echo_client 实例：

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

当客户端尝试连接到 EchoLauncher 协议时，服务器组件会启动。您应该会在设备日志 (ffx log) 中看到类似如下所示的输出：

[echo_server][I] Running echo launcher server
[echo_server][I] Incoming connection for fuchsia.examples.EchoLauncher
[echo_server][I] Got non-pipelined request
[echo_server][I] Got pipelined request
[echo_server][I] Got echo request for prefix pipelined:
[echo_server][I] Got echo request for prefix non pipelined:
[echo_client][I] Got echo response pipelined: hello!
[echo_client][I] Got echo response non pipelined: hello!

根据打印顺序，可以看出流水线式情况更快。流水线处理情况下的回显响应会先到达，即使非流水线处理的请求先发送，因为请求流水线处理可节省客户端与服务器之间的一次往返。请求流水线处理还可以简化代码。

如需进一步了解协议请求流水线处理，包括如何处理可能失败的协议请求，请参阅 FIDL API 规范。

终止 realm 组件以停止执行并清理组件实例：

ffx component destroy /core/ffx-laboratory:echo_realm