Comparing new C++ and high-level C++ language bindings

Quick reference

Here's how to recognize if a particular type/function/identifier in C++ code is part of the new C++ bindings or high-level C++ bindings.

Taking the examples.keyvaluestore.baseline library as example:

library examples.keyvaluestore.baseline;

type Item = struct {
    key string:128;
    value vector<byte>:64000;
};

type WriteError = flexible enum {
    UNKNOWN = 0;
    INVALID_KEY = 1;
    INVALID_VALUE = 2;
    ALREADY_EXISTS = 3;
};

@discoverable
open protocol Store {
    /// Writes an item to the store.
    flexible WriteItem(struct {
        attempt Item;
    }) -> () error WriteError;
};

Here are how the various FIDL elements will map to in the C++ bindings. Note that in the table "C++" refers to the new C++ bindings, and applies equally to both natural domain objects and wire domain objects. "Natural" refers to the natural domain objects in the new C++ bindings. "Wire" refers to the wire domain objects in the new C++ bindings.

Here's the most common way to set up a client:

  // Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
  // |zx::result| and it must be checked for errors.
  zx::result client_end = component::Connect<examples_canvas_baseline::Instance>();
  if (!client_end.is_ok()) {
    FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
                   << client_end.status_string();
    return -1;
  }

  // Create an instance of the event handler.
  EventHandler event_handler(loop);

  // Create an asynchronous client using the newly-established connection.
  fidl::Client client(std::move(*client_end), dispatcher, &event_handler);
  FX_LOGS(INFO) << "Outgoing connection enabled";

  // Connect to the protocol inside the component's namespace. This can fail so it's wrapped in a
  // |zx::result| and it must be checked for errors.
  zx::result client_end = component::Connect<examples_canvas_baseline::Instance>();
  if (!client_end.is_ok()) {
    FX_LOGS(ERROR) << "Synchronous error when connecting to the |Instance| protocol: "
                   << client_end.status_string();
    return -1;
  }

  // Create an instance of the event handler.
  EventHandler event_handler(loop);

  // Create an asynchronous client using the newly-established connection.
  fidl::WireClient client(std::move(*client_end), dispatcher, &event_handler);
  FX_LOGS(INFO) << "Outgoing connection enabled";

  // Connect to the protocol inside the component's namespace, then create an asynchronous client
  // using the newly-established connection.
  examples::canvas::baseline::InstancePtr instance_proxy;
  auto context = sys::ComponentContext::Create();
  context->svc()->Connect(instance_proxy.NewRequest(dispatcher));
  FX_LOGS(INFO) << "Outgoing connection enabled";

  instance_proxy.set_error_handler([&loop](zx_status_t status) {
    FX_LOGS(ERROR) << "Shutdown unexpectedly";
    loop.Quit();
  });

See the canvas example for the full code listing and explanation.

Here's the most common way to implement a server:

// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::Server<examples_canvas_baseline::Instance> {
  void AddLine(AddLineRequest& request, AddLineCompleter::Sync& completer) override {
    // ...
  }
};

// An implementation of the |Instance| protocol.
class InstanceImpl final : public fidl::WireServer<examples_canvas_baseline::Instance> {
  void AddLine(AddLineRequestView request, AddLineCompleter::Sync& completer) override {
    // ...
  }
};

// An implementation of the |Instance| protocol.
class InstanceImpl final : public examples::canvas::baseline::Instance {
  void AddLine(Line line) override {
    // ...
  }
};

See the canvas example for the full code listing and explanation.

New C++ bindings

The new C++ bindings supports both low-level and high-level use cases, by offering two families of generated domain objects, and corresponding client and server APIs that speak those types.

Natural types

• Optimized to meet the needs of high-level service programming.
• Represent data structures using idiomatic C++ types such as std::vector, std::optional, and std::string.
• Use smart pointers to manage heap allocated objects.
• Use zx::handle to manage handle ownership.
• Can convert data between their wire (e.g. fidl::StringView) and natural type representations (e.g. std::string).

Wire types

• Optimized to meet the needs of low-level systems programming while providing slightly more safety and features than the C bindings.
• Represent data structures whose memory layout coincides with the wire format, i.e. satisfying C++ Standard Layout. This opens the door to in-place encoding and decoding.
• Generated structures are views of an underlying buffer; they do not own memory.
• Support in-place access of FIDL messages.
• Provide fine-grained control over memory allocation.
• Use owned handle types such as zx::handle. Note that since generated structures are views of an underlying buffer, a parent structure will only own child handles if it also owns their underlying buffer. For example, a FIDL struct owns all the handles stored inline, but a FIDL vector of structs containing handles will be represented as a vector view, which will not own the out-of-line handles.

Client and server APIs

• Code generator produces more code compared to the C bindings. This includes constructors, destructors, copy/move functions, conversions between domain object families, protocol client implementations, and pure virtual server interfaces.
• Users implement a server by sub-classing a provided server interface and overriding the pure virtual methods for each operation.
• Clients supporting sync and async calls, and sync and async event handling.
• Requires C++17 or above.

Refer to the New C++ tutorial to get started.

High-level C++ bindings

• Optimized to meet the needs of high-level service programming.
• Represent data structures using idiomatic C++ types such as std::vector, std::optional, and std::string.
• Use smart pointers to manage heap allocated objects.
• Use zx::handle (libzx) to manage handle ownership.
• Can convert data from in-place FIDL buffers to idiomatic heap allocated objects.
• Can convert data from idiomatic heap allocated objects (e.g. std::string) to in-place buffers (e.g. as a fidl::StringView).
• Code generator produces more code compared to the C bindings. This includes constructors, destructors, protocol proxies, protocol stubs, copy/move functions, and conversions to/from in-place buffers.
• Client performs protocol dispatch by sub-classing a provided stub and implementing the virtual methods for each operation.
• Both async and synchronous clients are supported. However, the async clients are not thread-safe.
• Requires C++14 or above.

Refer to the HLCPP tutorial to get started.

Summary