class Client

|Client| is a client for sending and receiving FIDL wire messages, that

must be managed and used from a [synchronized async dispatcher][synchronized-dispatcher].

See |SharedClient| for a client that may be moved or cloned to different

dispatchers or arbitrary threads.

Generated FIDL APIs are accessed by 'dereferencing' the client value:

// Creates a client that speaks over |client_end|, on the |my_dispatcher| dispatcher.

fidl::Client client(std::move(client_end), my_dispatcher);

// Call the |Foo| method asynchronously, passing in a callback that will be

// invoked on a dispatcher thread when the server response arrives.

auto status = client->Foo(args, [] (Result result) {});

## Lifecycle

A client must be **bound** to an endpoint before it could be used. This

association between the endpoint and the client is called a "binding".

Binding a client to an endpoint starts the monitoring of incoming messages.

Those messages are appropriately dispatched: to response callbacks, to event

handlers, etc. FIDL methods (asynchronous or synchronous) may only be invoked

on a bound client.

Internally, a client is a lightweight reference to the binding, performing

its duties indirectly through that object, as illustrated by the simplified

diagram below:

references makes

client -------------> binding --------> FIDL call

This means that the client _object_ and the binding have overlapping but

slightly different lifetimes. For example, the binding may terminate in

response to fatal communication errors, leaving the client object alive but

unable to make any calls.

To stop the monitoring of incoming messages, one may **teardown** the

binding. When teardown is initiated, the client will not monitor new messages

on the endpoint. Ongoing callbacks will be allowed to run to completion. When

teardown is complete, further calls on the same client will fail. Unfulfilled

response callbacks will be dropped.

Destruction of a client object will initiate teardown.

Teardown will also be initiated when the binding encounters a terminal error:

- The server-end of the channel was closed.

- An epitaph was received.

- Decoding or encoding failed.

- An invalid or unknown message was encountered.

- Error waiting on, reading from, or writing to the channel.

In this case, the user will be notified of the detailed error via the

|on_fidl_error| method on the event handler.

## Thread safety

|Client| provides an easier to use API in exchange of a more restrictive

threading model:

- The provided |fdf_dispatcher_t| must be a [synchronized dispatcher][synchronized-dispatcher].

- The client must be bound on a task running on that dispatcher.

- The client must be destroyed on a task running on that dispatcher.

- FIDL method calls must be made from tasks running on that dispatcher.

- Responses are always delivered from dispatcher tasks, as are events.

The above rules are checked in debug builds at run-time. In short, the client

is local to its associated dispatcher.

Note that FIDL method calls must be synchronized with operations that consume

or mutate the |Client| itself:

- Assigning a new value to the |Client| variable.

- Moving the |Client| to a different location.

- Destroying the |Client|.

|Client| is suitable for systems with stronger sequential threading

guarantees. It is intended to be used as a local variable with fixed

lifetime, or as a member of a larger class where it is uniquely owned by

instances of that class. Destroying the |Client| is guaranteed to stop

message dispatch: since the client is destroyed on the dispatcher thread,

there is no opportunity of parallel callbacks to user code, and

use-after-free of user objects is naturally avoided during teardown.

See |SharedClient| for a client that supports binding and destroying on

arbitrary threads, at the expense of requiring two-phase shutdown.

[synchronized-dispatcher]:

https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/thread-safe-async#synchronized-dispatcher