| keywords: category:FuchsiaSystems,docType:Guide,category:FuchsiaFidl | |
| keywords_public: FIDL, C++, asynchronous, completer, ToAsync, server, tutorial, Fuchsia, wire domain objects, natural types | |
| description: This tutorial explains how to respond to FIDL requests asynchronously in C++ by using the ToAsync() method on a sync completer to obtain an async completer that can be used outside the request handler. | |
| <!-- These keywords are for search widget on fuchsia.dev. Do not remove. --> | |
| # Responding to requests asynchronously | |
| ## Prerequisites | |
| This tutorial builds on the [getting started tutorials][overview]. | |
| ## Overview | |
| The full example code for this tutorial is located at | |
| [//examples/fidl/cpp/server_async_completer][src]. | |
| In the `Echo` implementation from the initial [server tutorial][server-tut], the | |
| server code responded to `EchoString` requests using the completer: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server/main.cc" region_tag="impl-echo-string" adjust_indentation="auto" %} | |
| ``` | |
| Notice that the type of the completer ends with `::Sync`. Sync completers must | |
| be used before the handler returns. Enforcing this allows optimizations since | |
| the bookkeeping metadata for making a reply can be stack allocated. | |
| ## Respond asynchronously | |
| In many cases responding synchronously is infeasible. For example, the reply may | |
| need results from other asynchronous calls. To respond asynchronously, we must | |
| obtain an async completer from the sync completer, using `ToAsync`: | |
| ```cpp | |
| EchoStringCompleter::Async async_completer = completer.ToAsync(); | |
| ``` | |
| The resulting `async_completer` exposes the same API as `completer`, but can be | |
| moved away to be used at a later time. | |
| In the example code, the server makes the reply inside a delayed task, emulating | |
| a scenario where the server must execute a long running task before sending a | |
| response: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/server_async_completer/main.cc" region_tag="impl-echo-string" adjust_indentation="auto" %} | |
| ``` | |
| The server won't start handling any new requests until returning from the | |
| current handler method. After returning from `EchoString`, the server will | |
| monitor the endpoint for new FIDL messages, while the reply is scheduled one | |
| second into the future. This means if the client sent multiple `EchoString` | |
| requests in quick succession, we may have just as many concurrent async delayed | |
| tasks in flight. | |
| Note: if the async completer is captured by a lambda function, the lambda must | |
| be marked **mutable**, because making a reply using the completer mutates it | |
| such that duplicate replies will panic. | |
| ### Respond asynchronously in servers speaking wire domain objects | |
| You would use the same `ToAsync` operation when the server speaks | |
| [wire domain objects][wire-types], but pay extra attention to object lifetimes. | |
| In particular, the request views provided to method handlers do not own the | |
| request message. If an asynchronous task needs to use the request parameters | |
| after the `EchoString` method returns, we need to copy relevant fields to an | |
| owned type: | |
| ```cpp | |
| class EchoImpl : public fidl::WireServer<fuchsia_examples::Echo> { | |
| public: | |
| void EchoString(EchoStringRequestView request, EchoStringCompleter::Sync& completer) override { | |
| // Copy the contents of |request->value| (a fidl::StringView) to a string. | |
| std::string value_owned{request->value.get()}; | |
| async::PostDelayedTask( | |
| dispatcher_, | |
| [value = value_owned, completer = completer.ToAsync()]() mutable { | |
| completer.Reply(fidl::StringView::FromExternal(value)); | |
| }, | |
| zx::duration(ZX_SEC(1))); | |
| } | |
| // ... | |
| }; | |
| ``` | |
| For further information on the memory ownership, refer to | |
| [Memory ownership of wire domain objects][memory-ownership]. | |
| ## Run the example | |
| In order for the client and server to communicate using the `Echo` protocol, | |
| component framework must route the `fuchsia.examples.Echo` capability from the | |
| server to the client. For this tutorial, a [realm][glossary.realm] component is | |
| provided to declare the appropriate capabilities and routes. | |
| Note: You can explore the full source for the realm component at | |
| [`//examples/fidl/echo-realm`](/examples/fidl/echo-realm) | |
| 1. Configure your build to include the provided package that includes the | |
| echo realm, server, and client: | |
| ```posix-terminal | |
| fx set core.x64 --with //examples/fidl/cpp/server_async_completer:echo-cpp-async | |
| ``` | |
| 1. Build the Fuchsia image: | |
| ```posix-terminal | |
| fx build | |
| ``` | |
| 1. Run the `echo_realm` component. This creates the client and server component | |
| instances and routes the capabilities: | |
| ```posix-terminal | |
| ffx component run /core/ffx-laboratory:echo_realm fuchsia-pkg://fuchsia.com/echo-cpp-async#meta/echo_realm.cm | |
| ``` | |
| 1. Start the `echo_client` instance: | |
| ```posix-terminal | |
| ffx component start /core/ffx-laboratory:echo_realm/echo_client | |
| ``` | |
| The server component starts when the client attempts to connect to the `Echo` | |
| protocol. You should see output similar to the following in the device logs | |
| (`ffx log`). The leftmost column is the timestamp: | |
| ```none {:.devsite-disable-click-to-copy} | |
| [21611.962][echo_server][I] Running C++ echo server with natural types | |
| [21611.965][echo_server][I] Incoming connection for fuchsia.examples.Echo | |
| [21612.998][echo_client][I] (Natural types) got response: hello | |
| [21613.999][echo_client][I] (Natural types) got response: hello | |
| [21614.000][echo_client][I] (Natural types) got event: hello | |
| [21615.002][echo_client][I] (Wire types) got response: hello | |
| [21615.003][echo_client][I] (Natural types) got event: hello | |
| [21615.003][echo_server][I] Client disconnected | |
| ``` | |
| Note that it takes about one second between | |
| `Incoming connection for fuchsia.examples.Echo` and | |
| `(Natural types) got response: hello`, because the server is programmed to | |
| asynchronously delay the response by one second. | |
| Terminate the realm component to stop execution and clean up the component | |
| instances: | |
| ```posix-terminal | |
| ffx component destroy /core/ffx-laboratory:echo_realm | |
| ``` | |
| <!-- xrefs --> | |
| [src]: /examples/fidl/cpp/server_async_completer | |
| [server-tut]: /docs/development/languages/fidl/tutorials/cpp/basics/server.md | |
| [overview]: /docs/development/languages/fidl/tutorials/cpp/README.md | |
| [memory-ownership]: /docs/development/languages/fidl/tutorials/cpp/topics/wire-memory-ownership.md | |
| [wire-types]: /docs/development/languages/fidl/tutorials/cpp/basics/domain-objects.md#using-wire |