Please read on if you use the new C++ FIDL bindings (aka LLCPP).
TLDR: if you've enjoyed the fidl::Binding from HLCPP, now there's a counterpart in the new C++ bindings fidl::ServerBinding. We also improved fidl::BindServer along the way.
fidl::ServerBinding<Protocol> owns a FIDL server connection. When creating a binding, you would specify a pointer to the server implementation. Destroying the binding synchronously stops message dispatch and the FIDL runtime would no longer access the server implementation. Thus the idiomatic usage of a ServerBinding is to ensure that they're destroyed together, for example by embedding the binding as a member variable of a server implementation:
The last argument of a ServerBinding constructor is a CloseHandler, which is a callable that takes fidl::UnbindInfo. The close handler is invoked whenever the connection is closed due to errors or because the user initiated closing via a completer, unless the binding object is destroyed.
Therefore, under the idiomatic usage style above, the CloseHandler always notifies the server of connection closure, unless the user destroyed the server object proactively, in which case CloseHandler is discarded to prevent use-after-free errors. This could be a useful funnel to manage other kinds of resources whose lifecycle is tied to a FIDL connection.
Folks who have used fidl::BindServer may be familiar with some of its limitations:
fidl::BindServer returns a fidl::ServerBindingRef<Protocol> that does not own the connection. Discarding a server binding ref does nothing.
fidl::BindServer takes an on-unbound callback that is called asynchronously after unbinding completes and at which point the server object may already be destroyed, thus susceptible to use-after-free errors.
Those limitations were because fidl::BindServer was designed to support multithreaded usage and for a model where the binding owns the server object, which doesn't apply to all the FIDL server scenarios. With fidl::ServerBinding, we are addressing both limitations and filling the gap where the server object would like to own the binding instead. Both APIs are here to stay, and complement each other.
Head over to the FIDL examples to see how to use fidl::ServerBinding in a non-trivial application.
Finally, in order to guarantee that message dispatch is synchronously stopped when the binding is destroyed, fidl::ServerBinding does not support multithreaded/parallel usages. It is thread-unsafe, and would panic if it detects certain patterns of parallel access.
fidl::BindServer can now infer the protocol from the provided server endpoint argument. Previously, if you would like to implement two FIDL protocols on the same server implementation object, calls to fidl::BindServer became ambiguous. Now fidl::BindServer is able to figure out which "facet" of the server implementation it should bind to, based on the protocol type inside the fidl::ServerEnd<SomeProtocol> endpoint argument. Unless you are working with code that has not migrated to typed channels, there is no need to explicitly add a template parameter when calling fidl::BindServer.
See the migrations in this CL for more details.
Both improvements above apply to driver FIDL bindings in the V2 driver runtime. For example, you may use fdf::ServerBinding if you were previously using fdf::BindServer.
We're happy to answer or discuss them at fidl...@fuchsia.dev.
Cheers,
Yifei