sdk/lib/async_patterns/cpp/pending_call.h

// Copyright 2023 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef LIB_ASYNC_PATTERNS_CPP_PENDING_CALL_H_
#define LIB_ASYNC_PATTERNS_CPP_PENDING_CALL_H_

#include <lib/async_patterns/cpp/internal/tag.h>
#include <lib/fpromise/bridge.h>
#include <zircon/assert.h>

#include <utility>

namespace async_patterns {

template <typename F>
class Callback;

/// This type is usually returned from a |DispatcherBound::AsyncCall| or calling
/// |Callback<ReturnType(Args...)>|.
///
/// Let |Call| be a callable that takes zero arguments and returns |ReturnType|.
/// |PendingCall| represents a call that is yet to be run, and offers a variety
/// of ways to monitor its return value:
///
/// - The caller may discard the |PendingCall|, at which point the call will be
///   submitted for execution but its return value will be ignored.
///
/// - The caller may call `promise()` to get a `fpromise::promise<ReturnType>`
///   that will resolve if the call runs to completion, or be abandoned if the
///   call is dropped.
///
/// - The caller may call `Then` to specify an `async_patterns::Callback<void(R)>`
///   that will be called when the call runs to completion.
///
template <typename ReturnType, typename Call, typename Submit>
class PendingCall {
 public:
  /// Make the call if not already, and ignore the result.
  ///
  /// This leads to "fire-and-forget" behavior:
  ///
  ///     async_patterns::DispatcherBound<MyType> object;
  ///
  ///     // This returns a |PendingCall|. If we do nothing with the return
  ///     // value, that means making the call and we don't care about its result.
  ///     object.AsyncCall(&MyType::SomeMethod);
  ///
  ~PendingCall() {
    if (submit_.has_value()) {
      submit([call = std::move(call_)]() mutable { (void)call(); });
    }
  }

  /// Make the call and return a promise representing the return value of the call.
  ///
  /// The promise will resolve if the call runs to completion.
  ///
  /// The promise will be abandoned if the call is dropped, such as if the target object
  /// that is supposed to respond to this async call is already destroyed.
  ///
  /// Example:
  ///
  ///     async_patterns::Callback<std::string(int)> callback = ...;
  ///     fpromise::promise<int> promise = callback(42).promise();
  ///
  ///     // Now you can do something with the promise..
  ///     executor.schedule_task(
  ///         promise.and_then([] (int& value) { ... }));
  ///
  fpromise::promise<ReturnType> promise() && {
    fpromise::bridge<ReturnType> bridge;
    submit([call = std::move(call_), completer = bridge.completer.bind()]() mutable {
      using CallReturnType = decltype(call());
      static_assert(std::is_convertible_v<CallReturnType, ReturnType>);
      if constexpr (std::is_void_v<ReturnType>) {
        call();
        completer();
      } else {
        completer(call());
      }
    });
    return bridge.consumer.promise();
  }

  /// Arranges |on_result| to be called with the result of the async call.
  /// |on_result| is an |async_patterns::Callback<void(R)>|. |R| could be
  /// identical to |ReturnType| or be some other compatible type such as |const
  /// ReturnType&|. Typically, the owner will declare a |Receiver| to mint these
  /// callbacks.
  ///
  /// This allows two thread-unsafe objects living on different dispatchers to
  /// exchange messages in a ping-pong fashion. Example:
  ///
  ///     class Owner {
  ///      public:
  ///       Owner(async_dispatcher_t* owner_dispatcher)
  ///         : receiver_{this, owner_dispatcher},
  ///           background_loop_(&kAsyncLoopConfigNoAttachToCurrentThread),
  ///           background_{background_loop_.dispatcher(), std::in_place} {}
  ///
  ///       void StartDoingStuff() {
  ///         // Make a call on |Background|, and then receive the result
  ///         // at |DoneDoingStuff|.
  ///         background_.AsyncCall(&Background::DoStuff, 42)
  ///             .Then(receiver_.Once(&Owner::DoneDoingStuff));
  ///       }
  ///
  ///       void DoneDoingStuff(std::string result) {
  ///         // Check the result from |Background::DoStuff|.
  ///       }
  ///
  ///      private:
  ///       async_patterns::Receiver<Owner> receiver_;
  ///       async::Loop background_loop_;
  ///       async_patterns::DispatcherBound<Background> background_;
  ///     };
  ///
  /// See more in |async_patterns::DispatcherBound|.
  template <typename R>
  void Then(async_patterns::Callback<void(R)> on_result) && {
    constexpr bool kReceiverMatchesReturnValue =
        std::is_invocable_v<decltype(on_result), ReturnType>;
    static_assert(kReceiverMatchesReturnValue,
                  "The |async_patterns::Callback<void(R)>| must accept the return value "
                  "of the async call.");
    if constexpr (kReceiverMatchesReturnValue) {
      submit([call = std::move(call_), on_result = std::move(on_result)]() mutable {
        if constexpr (std::is_void_v<ReturnType>) {
          call();
          on_result();
        } else {
          on_result(call());
        }
      });
    }
  }

  //// |Call| should be a callable that takes zero arguments and returns |ReturnType|.
  ////
  //// |Submit| should be a callable that takes a |Call| and submits it for
  //// asynchronous execution. In addition, it should have an empty state reachable
  //// by calling |reset| and support checking for emptiness using |has_value|.
  PendingCall(Call call, Submit submit, internal::Tag<ReturnType>)
      : call_(std::move(call)), submit_(std::move(submit)) {}

  PendingCall(const PendingCall&) = delete;
  PendingCall& operator=(const PendingCall&) = delete;
  PendingCall(PendingCall&&) noexcept = delete;
  PendingCall& operator=(PendingCall&&) noexcept = delete;

 protected:
  template <typename Continuation>
  void CallWithContinuation(Continuation continuation) {
    submit([call = std::move(call_), c = std::move(continuation)]() mutable { c(call()); });
  }

 private:
  template <typename Task>
  void submit(Task&& task) {
    ZX_DEBUG_ASSERT(submit_.has_value());
    submit_(std::forward<Task>(task));
    submit_.reset();
  }

  Call call_;
  Submit submit_;
};

template <typename ReturnType, typename Call, typename Submit>
PendingCall(Call call, Submit submit, internal::Tag<ReturnType>)
    -> PendingCall<ReturnType, Call, Submit>;

}  // namespace async_patterns

#endif  // LIB_ASYNC_PATTERNS_CPP_PENDING_CALL_H_