sdk/lib/async_patterns/cpp/dispatcher_bound.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_DISPATCHER_BOUND_H_
#define LIB_ASYNC_PATTERNS_CPP_DISPATCHER_BOUND_H_

#include <lib/async/dispatcher.h>
#include <lib/async_patterns/cpp/internal/dispatcher_bound_storage.h>
#include <lib/async_patterns/cpp/pending_call.h>
#include <lib/fit/function.h>
#include <lib/fit/function_traits.h>
#include <lib/stdcompat/functional.h>
#include <zircon/assert.h>

#include <cstdlib>
#include <utility>

namespace async_patterns {

/// |DispatcherBound<T>| does not allow sending raw pointers to the wrapped
/// object. However, it is common for an async object to obtain its associated
/// |async_dispatcher_t*|. Often that can be accomplished with
/// |async_get_default_dispatcher|, but in case where that's not feasible, one
/// may specify the |async_patterns::PassDispatcher| constant in place of an
/// |async_dispatcher_t*|, at the argument location where the wrapped async
/// object desires a dispatcher, and |DispatcherBound| will automatically supply
/// the correct dispatcher that the async object is associated with.
constexpr auto PassDispatcher = internal::PassDispatcherT{};

/// |DispatcherBound<T>| enables an owner object living on some arbitrary thread,
/// to construct, call methods on, and destroy an object of type |T| that must be
/// used from a particular [synchronized async dispatcher][synchronized-dispatcher].
///
/// Thread-unsafe asynchronous types should be used from synchronized dispatchers
/// (e.g. a single-threaded async loop). Because the dispatcher may be running
/// code to manipulate such objects, one should not use the same objects from
/// other unrelated threads and cause data races.
///
/// However, it may not always be possible for an entire tree of objects to
/// live on the same async dispatcher, due to design or legacy constraints.
/// |DispatcherBound| helps one divide classes along dispatcher boundaries.
///
/// An example:
///
///     // |Background| always lives on a background dispatcher, provided
///     // at construction time.
///     class Background {
///      public:
///       explicit Background() {
///         // Perform some asynchronous work. The work is canceled if
///         // |Background| is destroyed.
///         task_.Post(async_get_default_dispatcher());
///       }
///
///      private:
///       void DoSomething();
///
///       // |task_| manages an async task that borrows the containing
///       // |Background| object and is not thread safe. It must be destroyed
///       // on the dispatcher to ensure that task cancellation is not racy.
///       async::TaskClosureMethod<Background, &Background::DoSomething> task_{this};
///     };
///
///     class Owner {
///      public:
///       // Asynchronously constructs a |Background| object on its dispatcher.
///       // Code in |Owner| and code in |Background| may run concurrently.
///       //
///       // The dispatcher will not be attached to the current thread, but will
///       // be attached to the loop thread. This way, the |Background| object
///       // can obtain a dispatcher from its constructor using
///       // |async_get_default_dispatcher|.
///       explicit Owner() :
///           background_loop_(&kAsyncLoopConfigNoAttachToCurrentThread),
///           background_{background_loop_.dispatcher(), std::in_place} {}
///
///      private:
///       // The async loop which will manage |Background| objects.
///       // This will always be paired with a |DispatcherBound| object.
///       async::Loop background_loop_;
///
///       // The |DispatcherBound| which manages |Background| on its loop.
///       // During destruction, |background_| will schedule the asynchronous
///       // destruction of the wrapped |Background| object on the dispatcher.
///       async_patterns::DispatcherBound<Background> background_;
///     };
///
/// |DispatcherBound| itself is thread-compatible.
///
/// ## Safety of sending arguments
///
/// When constructing |T| and calling member functions of |T|, it is possible to
/// pass additional arguments if the constructor or member function requires it.
/// The argument will be forwarded from the caller's thread into a heap data
/// structure, and later moved into the thread which would run the dispatcher
/// task asynchronously. Each argument must be safe to send to a different
/// thread. See |async_patterns::BindForSending| for the detailed requirements.
///
/// [synchronized-dispatcher]:
/// https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/thread-safe-async#synchronized-dispatcher
template <typename T>
class DispatcherBound {
 public:
  // Asynchronously constructs |T| on a task posted to |dispatcher|.
  ///
  /// Arguments after |std::in_place| are sent to the constructor of |T|.
  /// See |async_patterns::BindForSending| for detailed requirements on |args|.
  ///
  /// If you'd like to pass a |dispatcher| to |T| as a constructor argument,
  /// see |async_patterns::PassDispatcher|.
  ///
  /// If the dispatcher is shutdown, |T| will be synchronously constructed.
  template <typename... Args>
  explicit DispatcherBound(async_dispatcher_t* dispatcher, std::in_place_t, Args&&... args)
      : dispatcher_(dispatcher) {
    storage_.Construct<T, T>(dispatcher, std::forward<Args>(args)...);
  }

  /// Constructs a |DispatcherBound| that does not hold an instance of |T|.
  ///
  /// One may later construct |T| using |emplace| on the |dispatcher|.
  explicit DispatcherBound(async_dispatcher_t* dispatcher) : dispatcher_(dispatcher) {}

  /// Asynchronously constructs |T| on a task posted to the dispatcher.
  ///
  /// If this object already holds an instance of |T|, that older instance will
  /// be asynchronously destroyed on the dispatcher.
  ///
  /// If |T2| is specified, it must be same as |T| or a subclass. Then an instance
  /// of |T2| will be constructed. This can be useful for mocking: |T| may be some
  /// interface, and when constructing the object, either a fake (in unit tests)
  /// or a real concrete type (in production) will be specified.
  ///
  /// If you'd like to pass a |dispatcher| to |T| as a constructor argument,
  /// see |async_patterns::PassDispatcher|.
  ///
  /// See |async_patterns::BindForSending| for detailed requirements on |args|.
  template <typename T2 = T, typename... Args>
  void emplace(Args&&... args) {
    static_assert(std::is_base_of_v<T, T2>, "|T| must be a base class of |T2|.");
    reset();
    storage_.Construct<T, T2>(dispatcher_, std::forward<Args>(args)...);
  }

  /// Asynchronously calls |member|, a pointer to member function of |T|, using
  /// the provided |args|.
  ///
  /// |AsyncCall| returns a |PendingCall| object that lets you asynchronously
  /// monitor the result. You may either:
  ///
  /// - Make a fire-and-forget call, by discarding the returned object, or
  /// - Get a promise carrying the return value of the function by calling
  ///   `promise()` on the object, yielding a |fpromise::promise<ReturnType>|, or
  /// - Call `Then()` on the object and pass a |Callback<void(ReturnType)>|.
  ///
  /// See |PendingCall| for details.
  ///
  /// In particular, if |member| returns void, you could attach promises/callbacks
  /// that take void to asynchronously get notified when |member| has finished execution.
  ///
  /// Example:
  ///
  ///     class Owner {
  ///      public:
  ///       Owner(async_dispatcher_t* owner_dispatcher) : receiver_{this, owner_dispatcher} {
  ///         background_.emplace();
  ///         // Tell |background_| to |DoSomething|, then send back the return
  ///         // value to |Owner| using |receiver_|.
  ///         background_
  ///             .AsyncCall(&Background::DoSomething)
  ///             .Then(receiver_.Once(&Owner::DoneSomething));
  ///       }
  ///
  ///       void DoneSomething(Result result) {
  ///         // |Background::DoSomething| has completed with |result|...
  ///       }
  ///
  ///      private:
  ///       async::Loop background_loop_;
  ///       async_patterns::DispatcherBound<Background> background_{background_loop_.dispatcher()};
  ///       async_patterns::Receiver<Owner> receiver_;
  ///     };
  ///
  /// See |async_patterns::BindForSending| for detailed requirements on |args|.
  ///
  /// If |Background::DoSomething| is an overloaded member function, you may
  /// disambiguate it by spelling out its signature:
  ///
  ///     background_.AsyncCall<void(Result)>(&Background::DoSomething);
  ///
  /// The task will be synchronously called if the dispatcher is shutdown.
  template <typename Member, typename... Args>
  auto AsyncCall(Member T::*member, Args&&... args) {
    ZX_ASSERT(has_value());
    constexpr bool kIsInvocable = std::is_invocable_v<Member, Args...>;
    static_assert(kIsInvocable,
                  "|Member| must be callable with the provided |Args|. "
                  "Check that you specified each argument correctly to the |member| function.");
    if constexpr (kIsInvocable) {
      CheckArgs(typename fit::callable_traits<Member>::args{});
      return UnsafeAsyncCallImpl(member, std::forward<Args>(args)...);
    }
  }

  /// Typically, asynchronous classes would contain internal self-pointers that
  /// make moving dangerous, so we disable moves here for now.
  DispatcherBound(DispatcherBound&&) noexcept = delete;
  DispatcherBound& operator=(DispatcherBound&&) noexcept = delete;

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

  /// If |has_value|, asynchronously destroys the managed |T| on a task
  /// posted to the dispatcher.
  ///
  /// If the dispatcher is shutdown, |T| will be synchronously destroyed.
  ~DispatcherBound() { reset(); }

  /// If |has_value|, asynchronously destroys the managed |T| on a task
  /// posted to the dispatcher.
  ///
  /// If the dispatcher is shutdown, |T| will be synchronously destroyed.
  void reset() {
    if (!has_value()) {
      return;
    }
    storage_.Destruct(dispatcher_);
  }

  /// Returns if this object holds an instance of |T|.
  bool has_value() const { return storage_.has_value(); }

 protected:
  /// Calls an arbitrary |callable| asynchronously on the |dispatcher_|.
  template <template <typename, typename, typename> typename Builder = PendingCall,
            typename Callable, typename... Args>
  auto UnsafeAsyncCallImpl(Callable&& callable, Args&&... args) {
    using Result = std::invoke_result_t<Callable, T*, Args...>;
    return storage_.AsyncCall<Builder, Result, T>(dispatcher_, std::forward<Callable>(callable),
                                                  std::forward<Args>(args)...);
  }

  template <typename... Args>
  constexpr void CheckArgs(fit::parameter_pack<Args...>) {
    internal::CheckArguments<Args...>::Check();
  }

 private:
  async_dispatcher_t* dispatcher_;
  internal::DispatcherBoundStorage storage_;
};

/// Constructs a |DispatcherBound<T>| that holds an instance of |T| by sending
/// the |args| to the constructor of |T| run from a |dispatcher| task.
///
/// See |DispatcherBound| constructor for details.
template <typename T, typename... Args>
DispatcherBound<T> MakeDispatcherBound(async_dispatcher_t* dispatcher, Args&&... args) {
  return DispatcherBound<T>{dispatcher, std::in_place, std::forward<Args>(args)...};
}

}  // namespace async_patterns

#endif  // LIB_ASYNC_PATTERNS_CPP_DISPATCHER_BOUND_H_