class NaturalThenable

|Then| takes a callback, and implements "at most once" semantics: it

invokes the callback at most once until the client goes away. In other

words, the callback passivates when the client object goes away.

This is useful when the callback receiver object has the same lifetime as

the client object. It is an optimization for when the client and the

receiver (typically `this`) are tightly coupled and always destroyed

together in a sequential context, allowing us to avoid additional

cancellation mechanisms such as `WeakPtrFactory`. When the client is a

member field of `this`, the answer is almost always using `This` to silence

pending callbacks at destruction time.

Example syntax:

class Foo {

public:

void DoSomething() {

client_->SomeMethod(request).Then(fit::bind_member

<

&Foo

::HandleResult>(this));

}

void HandleResult(fidl::Result

<SomeMethod

>

&

result) {

// Handle the result from making the call in |DoSomething|.

// If |Foo| is destroyed, any pending callbacks are discarded.

}

private:

fidl::Client

<MyProtocol

> client_;

};

When using |SharedClient|, note that |Then| alone is not sufficient for

memory safety: |SharedClient| allows the user to destroy the client

from an arbitrary thread, which may race with in-progress callbacks. Always

use thread-safe reference counting or teardown observers to maintain

correct receiver lifetime.

This |ThenExactlyOnce| overload takes an arbitrary callable. |callback| is

called exactly once, even after the client object was destroyed. It is the

responsibility of the user to write any appropriate cancellation logic;

they have to be careful about the lifetimes of any objects captured by the

callable.

NOTE: This should almost never be used if the lambda captures `this` and

the client is a member of `this`, because the client may asynchronously

notify the outer object of errors after its destruction, to prevent

re-entrancy. Prefer |Then| over |ThenExactlyOnce| when writing

object-oriented code.

This method is useful in unit tests, and for integrating with objects that

want "exactly once" semantics, and which could be retained forever without

breaking memory safety:

- fpromise::promise completers

- FIDL server method completers, if the server is not unbound at the same

event loop iteration when the client is destroyed.