sdk/lib/async_patterns/cpp/task_scope.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_TASK_SCOPE_H_
#define LIB_ASYNC_PATTERNS_CPP_TASK_SCOPE_H_

#include <lib/async/dispatcher.h>
#include <lib/async_patterns/cpp/internal/task_queue.h>
#include <lib/fit/function.h>
#include <lib/zx/time.h>
#include <zircon/compiler.h>

namespace async_patterns {

/// |TaskScope| lets you post asynchronous tasks that are silently discarded when
/// the |TaskScope| object is destroyed. In contrast, tasks posted using
/// |async::PostTask|, |async::PostDelayedTask|, and so on will always run unless
/// the dispatcher is shutdown -- there is no separate mechanism to cancel them.
///
/// The task scope is usually a member of some bigger async business logic
/// object. By associating the lifetime of the posted async tasks with this
/// object, one can conveniently capture or borrow other members from the async
/// tasks without the need for reference counting to achieve memory safety.
/// Example:
///
///     class AsyncCounter {
///      public:
///       explicit AsyncCounter(async_dispatcher_t* dispatcher) : tasks_(dispatcher) {
///         // Post some tasks to asynchronously count upwards.
///         //
///         // It is okay if |AsyncCounter| is destroyed before some of these tasks
///         // come due. Those tasks will be discarded so they will not end up accessing
///         // a destroyed object.
///         tasks_.Post([this] { count_++ });
///         tasks_.PostDelayed([this] { count_++ }, zx::sec(1));
///         tasks_.PostDelayed(fit::bind_member<&AsyncCounter::CheckCount>(this), zx::sec(5));
///       }
///
///       void CheckCount() {
///         assert(count_ == 2);
///       }
///
///      private:
///       TaskScope tasks_;
///       int count_ = 0;
///     };
///
/// |TaskScope| is thread-unsafe, and must be used and managed from a
/// [synchronized dispatcher][synchronized-dispatcher].
///
/// [synchronized-dispatcher]:
/// https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/thread-safe-async#synchronized-dispatcher
class TaskScope {
 private:
  // |F| must take zero arguments ard return void.
  template <typename F>
  using require_nullary_fn = std::enable_if_t<std::is_void_v<std::invoke_result_t<F>>>;

 public:
  /// Creates a |TaskScope| that will post all tasks to the provided |dispatcher|.
  explicit TaskScope(async_dispatcher_t* dispatcher);

  /// Destroying the |TaskScope| synchronously destroys all pending tasks. If a
  /// task attempts to reentrantly post more tasks into the |TaskScope| within
  /// its destructor, those tasks will be synchronously destroyed too.
  ~TaskScope();

  /// Schedules to invoke |handler| with a deadline of now.
  ///
  /// |handler| should be a |void()| callable object.
  ///
  /// The handler will not run if |TaskScope| is destroyed before it comes due.
  /// The handler will not run if the dispatcher shuts down before it comes due.
  /// In both cases, the handler will be synchronously destroyed during task scope
  /// destruction/dispatcher shutdown.
  ///
  /// This is a drop-in replacement for |async::PostTask|.
  template <typename Closure>
  require_nullary_fn<Closure> Post(Closure&& handler) {
    PostImpl(internal::Task::Box(std::forward<Closure>(handler)));
  }

  /// Schedules to invoke |handler| with a deadline expressed as a |delay| from now.
  ///
  /// |handler| should be a |void()| callable object.
  ///
  /// The handler will not run if |TaskScope| is destroyed before it comes due.
  /// The handler will not run if the dispatcher shuts down before it comes due.
  /// In both cases, the handler will be synchronously destroyed during task scope
  /// destruction/dispatcher shutdown.
  ///
  /// This is a drop-in replacement for |async::PostDelayedTask|.
  template <typename Closure>
  require_nullary_fn<Closure> PostDelayed(Closure&& handler, zx::duration delay) {
    PostImpl(DelayedTask::Box(std::forward<Closure>(handler), this), delay);
  }

  /// Schedules to invoke |handler| with the specified |deadline|.
  ///
  /// |handler| should be a |void()| callable object.
  ///
  /// The handler will not run if |TaskScope| is destroyed before it comes due.
  /// The handler will not run if the dispatcher shuts down before it comes due.
  /// In both cases, the handler will be synchronously destroyed during task scope
  /// destruction/dispatcher shutdown.
  ///
  /// This is a drop-in replacement for |async::PostTaskForTime|.
  template <typename Closure>
  require_nullary_fn<Closure> PostForTime(Closure&& handler, zx::time deadline) {
    PostImpl(DelayedTask::Box(std::forward<Closure>(handler), this), deadline);
  }

 private:
  class DelayedTask : public list_node_t, public async_task_t {
   public:
    explicit DelayedTask(TaskScope* owner);
    virtual ~DelayedTask() = default;

    bool Post(async_dispatcher_t* dispatcher, zx::time deadline);
    virtual void Run() = 0;

    template <typename Callable>
    static std::unique_ptr<DelayedTask> Box(Callable&& callable, TaskScope* owner) {
      class TaskImpl final : public DelayedTask {
       public:
        explicit TaskImpl(Callable&& callable, TaskScope* owner)
            : DelayedTask(owner), callable_(std::forward<Callable>(callable)) {}
        void Run() final { callable_(); }

       private:
        Callable callable_;
      };
      return std::make_unique<TaskImpl>(std::forward<Callable>(callable), owner);
    }

   private:
    static void Handler(async_dispatcher_t* dispatcher, async_task_t* task, zx_status_t status);

    TaskScope* owner_;
  };

  void PostImpl(std::unique_ptr<internal::Task> task);
  void PostImpl(std::unique_ptr<DelayedTask> task, zx::duration delay);
  void PostImpl(std::unique_ptr<DelayedTask> task, zx::time deadline);
  void RemoveDelayedTask(DelayedTask* task) __TA_EXCLUDES(checker_);
  void RemoveDelayedTaskLocked(DelayedTask* task) __TA_REQUIRES(checker_);

  async_dispatcher_t* dispatcher_;
  async::synchronization_checker checker_;
  internal::TaskQueue queue_ __TA_GUARDED(checker_);

  // A list of |DelayedTask|.
  list_node_t delayed_task_list_ __TA_GUARDED(checker_) = LIST_INITIAL_VALUE(delayed_task_list_);

  // If true, tasks are discarded instead of posted.
  bool stopped_ __TA_GUARDED(checker_) = false;
};

}  // namespace async_patterns

#endif  // LIB_ASYNC_PATTERNS_CPP_TASK_SCOPE_H_