src/developer/debug/zxdb/client/async_task_tree.h

// Copyright 2026 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 SRC_DEVELOPER_DEBUG_ZXDB_CLIENT_ASYNC_TASK_TREE_H_
#define SRC_DEVELOPER_DEBUG_ZXDB_CLIENT_ASYNC_TASK_TREE_H_

#include <lib/fit/function.h>

#include <memory>
#include <vector>

#include "src/developer/debug/zxdb/client/async_task.h"
#include "src/developer/debug/zxdb/client/frame.h"
#include "src/lib/fxl/macros.h"
#include "src/lib/fxl/memory/weak_ptr.h"

namespace zxdb {

class Err;
class Stack;

// Represents a logical tree of async tasks, possibly associated with an executor.
//
// This object is like the "stack" of asynchronous tasks that are registered with some asynchronous
// runtime (from here on, just "the runtime").
//
// Unlike the Stack, which is allocated by the operating system at thread creation time, and has a
// single list of stack frames, asynchronous runtimes are opted in by particular programs if they so
// choose, which can operate in single or multithreaded environments, and coordinate trees of
// asynchronous tasks. The tasks may be in many states, such as waiting on I/O operations,
// suspended, completed, or any other of many states that are defined by a particular runtime. These
// asynchronous tasks will always have some memory associated with them to hold the current state
// (e.g. "stackless" coroutines), or they may contain a small "stack" region within themselves to
// perform allocations (e.g. "stackful" coroutines).
//
// Our goal is to abstract away as many of these details as possible from different runtimes and
// languages to present a common interface for interacting with these objects for inspection and
// traversal, just like stack frames are today.
//
// The interface for this class is the entrypoint for interacting with the runtime and all of the
// currently live task objects that are registered with the runtime.
//
// The suppliers are responsible for providing the Delegate interface to construct new task objects
// and inject them into the tree.
//
// The consumers may use the getters or provided iteration methods to perform operations against the
// tasks present in the tree.
class AsyncTaskTree {
 public:
  class Delegate {
   public:
    virtual ~Delegate() = default;
    // Requests that the AsyncTaskTree be provided with a new set of tasks. The implementation
    // should asynchronously request the task information, call AsyncTaskTree::SetTasks(), then
    // issue the callback to indicate completion. The optionally provided |frame| argument to the
    // callback is plumbed from callers of |AsyncTaskTree::Sync| so that they may use the correct
    // stack frame's EvalContext.
    virtual void SyncAsyncTasks(fit::callback<void(const Err&, const Frame* frame)> callback) = 0;
  };

  explicit AsyncTaskTree(Delegate* delegate);
  ~AsyncTaskTree();

  fxl::WeakPtr<AsyncTaskTree> GetWeakPtr();

  // Returns whether or not the task tree is non-empty. If this method returns true it means the
  // traversal methods below will work without calling |Sync| first. This is primarily an
  // optimization for callers to use to avoid calling |Sync| repeatedly on a task tree that has
  // already been cached.
  bool has_tasks() const { return !root_tasks_.empty(); }

  // Requests that all task information be updated. Automatically requests the full stack if it
  // isn't already present.
  void Sync(Stack& stack, fit::callback<void(const Err&, const Frame* frame)> callback);

  // Provides a new set of root tasks.
  void SetTasks(std::vector<std::unique_ptr<AsyncTask>> tasks);

  // Removes all tasks.
  void ClearTasks();

  struct TaskEntry {
    const AsyncTask& task;
    int depth = 0;
  };

  // The following are efficient accessor methods for all of the tasks in the tree. The root tasks
  // are not exposed publicly from this class intentionally so that callers use one of the below
  // iteration methods to accomplish their goals rather than implementing their own recursion
  // through the tree that could blow up our stack for large task trees.

  // Performs a depth-first iteration of all tasks in the tree, calling |fn| on each entry.
  void ForEach(fit::function<void(const TaskEntry&)> fn) const;

  // Transforms the tree of AsyncTasks into a tree of arbitrary Node types.
  //
  // This method uses an iterative, stack-based approach to traverse the tree,
  // avoiding potential stack overflow issues that can occur with recursive
  // traversal of deeply nested task structures. Prefer using this or ForEach
  // when possible.
  //
  // Parameters:
  //   populate_fn: A callable with signature `void(const AsyncTask& task, Node*
  //                node)`. It is responsible for copying data from the `task`
  //                into the `node`.
  //   children_fn: A callable with signature `std::vector<Node>*(Node* node)`.
  //                It must return a pointer to a `std::vector` that holds the
  //                children of the given `node`. This allows the Map function
  //                to resize the container and push child nodes onto its
  //                processing stack.
  //
  // Example:
  // ```cpp
  //   struct MyNode {
  //     std::string name;
  //     std::vector<MyNode> children;
  //   };
  //
  //   std::vector<MyNode> result = tree.Map<MyNode>(
  //       [](const zxdb::AsyncTask& task, MyNode* node) {
  //         node->name = task.GetIdentifier().GetFullName();
  //       },
  //       [](MyNode* node) {
  //         return &node->children;
  //       });
  // ```
  template <typename Node, typename PopulateFn, typename ChildrenFn>
  std::vector<Node> Map(PopulateFn populate_fn, ChildrenFn children_fn) const {
    std::vector<Node> root_nodes;
    auto roots = GetRootTasks();
    root_nodes.resize(roots.size());

    struct StackItem {
      AsyncTask::Ref task;
      Node* node;
    };
    std::vector<StackItem> stack;

    for (size_t i = 0; i < roots.size(); ++i) {
      stack.push_back({roots[i], &root_nodes[i]});
    }

    while (!stack.empty()) {
      StackItem item = stack.back();
      stack.pop_back();

      populate_fn(item.task.get(), item.node);

      auto children = item.task.get().GetChildren();
      if (!children.empty()) {
        if (std::vector<Node>* out_children = children_fn(item.node)) {
          out_children->resize(children.size());
          for (size_t i = 0; i < children.size(); ++i) {
            stack.push_back({children[i], &(*out_children)[i]});
          }
        }
      }
    }

    return root_nodes;
  }

 private:
  std::vector<AsyncTask::Ref> GetRootTasks() const;

  Delegate* delegate_;

  // These are the roots of the task tree.
  std::vector<std::unique_ptr<AsyncTask>> root_tasks_;

  fxl::WeakPtrFactory<AsyncTaskTree> weak_factory_;

  FXL_DISALLOW_COPY_AND_ASSIGN(AsyncTaskTree);
};

}  // namespace zxdb

#endif  // SRC_DEVELOPER_DEBUG_ZXDB_CLIENT_ASYNC_TASK_TREE_H_