| keywords: docType:Guide,category:FuchsiaSDK,category:FuchsiaFidl | |
| keywords_public: FIDL, C++, domain objects, natural types, wire types, bindings, Fuchsia, tutorial, structs, unions, tables, bits, enums, conversion, persistence | |
| description: This tutorial explains how to use natural and wire domain objects in C++ FIDL bindings, covering their differences, usage for various FIDL types, and how to convert between them. | |
| <!-- These keywords are for search widget on fuchsia.dev. Do not remove. --> | |
| # Using natural and wire domain objects | |
| ## Prerequisites | |
| This tutorial builds on the [Compiling FIDL][fidl-intro] tutorial. | |
| For more information on other FIDL tutorials, see the [overview][overview]. | |
| ## Overview | |
| This tutorial details how to use the natural and wire | |
| [domain objects][glossary.domain-object] by creating a unit test exercising | |
| those data types. | |
| This document covers how to complete the following tasks: | |
| * [Add the C++ bindings of a FIDL library as a build dependency](#add-dep). | |
| * [Include the bindings header into your code](#include-cpp-bindings). | |
| * [Using natural domain objects](#using-natural). | |
| * [Using wire domain objects](#using-wire). | |
| * [Convert between natural and wire domain objects](#convert-natural-wire). | |
| ## Using the domain objects example code | |
| The example code accompanying this tutorial is located in your Fuchsia checkout | |
| at `//examples/fidl/cpp/domain_objects`. It consists of a unit test component | |
| and its containing package. For more information about building unit test | |
| components, see [Build components][build-components]. | |
| You may build and run the example on a running instance of Fuchsia emulator via | |
| the following: | |
| ```posix-terminal | |
| # Add the domain objects unit test to the build. | |
| # This only needs to be done once. | |
| fx set core.x64 --with //examples/fidl/cpp/domain_objects | |
| # Run the domain objects unit test. | |
| fx test -vo fidl-examples-domain-objects-cpp-test | |
| ``` | |
| ## Add the C++ bindings of a FIDL library as a build dependency {#add-dep} | |
| * {GN build} | |
| For each FIDL library declaration, such as the one in | |
| [Compiling FIDL][fidl-intro], the C++ bindings code for that library is | |
| generated under the original target name suffixed with `_cpp`: | |
| ```bazel | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/BUILD.bazel" region_tag="binding-dep" adjust_indentation="auto" exclude_regexp="^$" %} | |
| ``` | |
| The `test` target looks like: | |
| ```bazel | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/BUILD.bazel" region_tag="test" adjust_indentation="auto" highlight="9" %} | |
| ``` | |
| Note the line which adds the dependency on the C++ bindings by referencing that | |
| `_cpp` target. | |
| (Optional) To view the generated bindings: | |
| 1. Build using `fx build`. | |
| 2. Change to the generated files directory: | |
| `out/default/fidling/gen/examples/fidl/fuchsia.examples/fuchsia.examples/cpp/fidl/fuchsia.examples/cpp`, | |
| where the generated files are located. You may need to change `out/default` | |
| if you have set a different build output directory. You can check your build | |
| output directory with `cat .fx-build-dir`. | |
| For more information on how to find generated bindings code, see | |
| [Viewing generated bindings code][generated-code]. | |
| * {Bazel build} | |
| <!-- TODO(https://fxbug.dev/42062701): Link to real samples once those are ready.--> | |
| When depending on the FIDL library not from the SDK in a Bazel build, you must | |
| specify the type(s) of bindings to generate: | |
| ```bazel | |
| # Given a FIDL library declaration like the following | |
| fuchsia_fidl_library( | |
| name = "fuchsia.examples", | |
| srcs = [ | |
| "echo.test.fidl", | |
| "types.test.fidl", | |
| ], | |
| cc_bindings = [ | |
| "cpp", | |
| "cpp_wire", | |
| ], | |
| library = "fuchsia.examples", # Optional. | |
| visibility = ["//visibility:public"], | |
| ) | |
| ``` | |
| If the FIDL library is from the Bazel SDK, the above step is not needed. | |
| The C++ bindings code for a FIDL library is generated under the original | |
| target name suffixed with `_cpp_cc`: | |
| ```bazel | |
| deps = [ | |
| # Example when depending on an SDK library, `fuchsia.io`. | |
| "@fuchsia_sdk//fidl/fuchsia.io:fuchsia.io_cpp_cc", | |
| # Example when depending on a local FIDL library, `fuchsia.examples` | |
| # defined above. | |
| # Suppose the library lives in the `//path/to/fidl/library` folder. | |
| "//path/to/fidl/library:fuchsia.examples_cpp_cc", | |
| # ... other dependencies ... | |
| ] | |
| ``` | |
| ## Include the bindings header into your code {#include-cpp-bindings} | |
| After adding the build dependency, you may include the bindings header. The | |
| include pattern is `#include <fidl/my.library.name/cpp/fidl.h>`. | |
| The following include statement at the top of `domain_objects/main.cc` includes | |
| the bindings and makes the generated APIs available to the source code: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="include" %} | |
| ``` | |
| ## Using natural domain objects {#using-natural} | |
| Natural types are the ergonomics and safety focused flavor of C++ domain | |
| objects. A tree of FIDL values is represented as a tree of C++ objects with | |
| hierarchical ownership. That means if a function receives some object of natural | |
| type, it can assume unique ownership of all child objects in the entire tree. | |
| The tree is torn down when the root object goes out of scope. | |
| At a high level the natural types embrace `std::` containers and concepts. For | |
| example, a [table][table] is represented as a collection of | |
| `std::optional<Field>`s. A [vector][vector] is `std::vector<T>`, etc. They also | |
| implement idiomatic C++ moves, copies, and equality. For example, a | |
| [resource][resource] type is move-only, while a value type will implement both | |
| copy and moves, where moves are designed to optimize the transfer of objects. | |
| Moving a table doesn't make it empty (it just recursively moves the fields), | |
| similar to `std::optional`. | |
| ### Natural bits | |
| Using the strict [`fuchsia.examples/FileMode`][fidl-file] FIDL type and the | |
| flexible [`fuchsia.examples/FlexibleFileMode`][fidl-file] FIDL type as examples: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="natural-bits" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| ### Natural enums | |
| Using the strict [`fuchsia.examples/LocationType`][fidl-file] FIDL type and the | |
| flexible [`fuchsia.examples/FlexibleLocationType`][fidl-file] FIDL type as | |
| examples: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="natural-enums" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| ### Natural structs | |
| Natural structs are straightforward record objects that expose const and mutable | |
| accessors. Using the [`fuchsia.examples/Color`][fidl-file] FIDL type as an | |
| example: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="natural-structs" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| ### Natural unions | |
| Natural unions are sum types similar to `std::variant`. Using the strict | |
| [`fuchsia.examples/JsonValue`][fidl-file] FIDL type and the flexible | |
| [`fuchsia.examples/FlexibleJsonValue`][fidl-file] FIDL type as examples: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="natural-unions" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| ### Natural tables | |
| Natural tables are record types where every field is optional. Using the | |
| [`fuchsia.examples/User`][fidl-file] FIDL type as an example: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="natural-tables" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| ## Using wire domain objects {#using-wire} | |
| Wire types are the performance oriented flavor of C++ domain objects. Differing | |
| from natural types which maintain hierarchical object ownership, wire objects | |
| never own their out-of-line children. Whether a child object is stored inline or | |
| out-of-line is determined by the [FIDL wire format][fidl-wire-format]. | |
| Natural types may implicitly heap allocate the necessary storage. Conversely, | |
| the user has complete control over memory allocation of wire types. For example, | |
| you may allocate the elements of a FIDL vector on the stack, from a memory pool, | |
| or as part of a larger object. The wire vector type, `fidl::VectorView<T>`, is | |
| an unowned view type consisting of a raw pointer and a length. One may send the | |
| vector as part of a FIDL request without extra heap allocations by borrowing the | |
| elements via this type. | |
| To distinguish from the natural types, wire types from a FIDL library are | |
| defined in the `...::wire` nested namespace, e.g. `fuchsia_my_library::wire`. | |
| The prevalence of unowned pointers in wire types makes them flexible but very | |
| unsafe. This tutorial will focus on the safer side of using wire types based on | |
| memory arenas. For more advanced usages involving unsafe memory borrows, refer | |
| to [Memory ownership of wire domain objects][wire-memory-ownership]. | |
| ### Wire bits and enums | |
| Because bits and enums have a very simple memory layout and do not have any | |
| out-of-line children, the wire types for FIDL bits and enums are the same as | |
| their natural type counterparts. To stay coherent with the overall namespace | |
| naming profiles, bits and enums are aliased into the `fuchsia_my_library::wire` | |
| nested namespace, appearing alongside wire structs, unions, and tables. | |
| Using the [`fuchsia.examples/FileMode`][fidl-file] FIDL bits as an example, | |
| `fuchsia_examples::wire::FileMode` is a type alias of | |
| `fuchsia_examples::FileMode`. | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="wire-bits" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| Similarly, using the [`fuchsia.examples/LocationType`][fidl-file] FIDL enum as | |
| an example, `fuchsia_examples::wire::LocationType` is a type alias of | |
| `fuchsia_examples::LocationType`. | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="wire-enums" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| ### Wire structs | |
| Wire structs are simple C++ structs that hold public member variables. Using the | |
| [`fuchsia.examples/Color`][fidl-file] FIDL type as an example: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="wire-structs" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| ### Wire unions | |
| Wire unions are sum types with a memory layout akin to a discriminator tag | |
| followed by a reference to the active member. Using the strict | |
| [`fuchsia.examples/JsonValue`][fidl-file] FIDL type and the flexible | |
| [`fuchsia.examples/FlexibleJsonValue`][fidl-file] FIDL type as examples: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="wire-unions" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| ### Wire tables | |
| Wire tables are record types where every field is optional. Differing from | |
| [natural tables](#natural-tables), wire tables do not own any member field. | |
| Copying a wire table is akin to aliasing (copying) a pointer. Similar to | |
| pointers, moving a wire table is an anti-pattern because that equates to a copy. | |
| Because of the memory layout constraints of wire tables, one always use an | |
| associated `Builder` type to create new instances. Once a table is built, one | |
| may not add new members or clear existing members. | |
| Using the [`fuchsia.examples/User`][fidl-file] FIDL type as an example: | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="wire-tables" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| For more information on the bindings, see the | |
| [bindings reference][bindings-ref]. | |
| ## Convert between natural and wire domain objects {#convert-natural-wire} | |
| To streamline interoperability, you may call `fidl::ToWire` and | |
| `fidl::ToNatural` functions to convert between wire and natural domain objects. | |
| Using the [`fuchsia.examples/User`][fidl-file] FIDL type as an example: | |
| ### Convert from natural to wire: `fidl::ToWire` | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="natural-to-wire" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| ### Convert from wire to natural: `fidl::ToNatural` | |
| ```cpp | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/cpp/domain_objects/main.cc" region_tag="wire-to-natural" adjust_indentation="auto" exclude_regexp="^TEST|^}" %} | |
| ``` | |
| ## Persist natural and wire domain objects | |
| You may use `fidl::Persist` to serialize a natural or wire domain object into | |
| a byte vector, the primary use case being long term data persistence. | |
| `fidl::Unpersist` deserializes and copies a sequence of bytes into some instance | |
| of natural domain object. | |
| `fidl::InplaceUnpersist` deserializes a sequence of bytes into some instance of | |
| wire domain object, mutating the bytes in the process. | |
| <<../../../widgets/_persistence.md>> | |
| <!-- xrefs --> | |
| [build-components]: /docs/development/components/build.md#unit-tests | |
| [generated-code]: /docs/development/languages/fidl/guides/generated-code.md#c-family | |
| [bindings-ref]: /docs/reference/fidl/bindings/cpp-bindings.md | |
| [fidl-intro]: /docs/development/languages/fidl/tutorials/fidl.md | |
| [fidl-file]: /examples/fidl/fuchsia.examples/types.test.fidl | |
| [fidl-wire-format]: /docs/reference/fidl/language/wire-format/README.md | |
| [glossary.domain-object]: /docs/glossary#domain-object | |
| [overview]: /docs/development/languages/fidl/tutorials/overview.md | |
| [resource]: /docs/reference/fidl/language/language.md#value-vs-resource | |
| [server-tut]: /docs/development/languages/fidl/tutorials/cpp/basics/server.md | |
| [table]: /docs/reference/fidl/language/language.md#tables | |
| [vector]: /docs/reference/fidl/language/language.md#vectors | |
| [wire-memory-ownership]: /docs/development/languages/fidl/tutorials/cpp/topics/wire-memory-ownership.md |