[orc-rt] Add QueueingTaskDispatcher API. (#172401)

lhames · web-flow · commit f2be60c40ef4 · 2025-12-16T17:43:36.000+11:00
QueueingTaskDispatcher adds Tasks to a the back of a double ended queue
that is accessible to clients via the `pop_back` and `pop_front`
methods. Clients can manually take and run tasks, or call
`runLIFOUntilEmpty` or `runFIFOUntilEmpty` to run tasks until the queue
is empty.

QueueingTaskDispatcher is intended for use in unit tests, and as a
foundation for blocking convenience APIs in environments without
threads. QueueingTaskDispatcher should generally be avoided, and
ThreadPoolTaskDispatcher preferred, where threads are available.
diff --git a/orc-rt/include/CMakeLists.txt b/orc-rt/include/CMakeLists.txt
@@ -12,6 +12,7 @@ set(ORC_RT_HEADERS
     orc-rt/IntervalSet.h
     orc-rt/Math.h
     orc-rt/MemoryFlags.h
+    orc-rt/QueueingTaskDispatcher.h
     orc-rt/ResourceManager.h
     orc-rt/RTTI.h
     orc-rt/ScopeExit.h
diff --git a/orc-rt/include/orc-rt/QueueingTaskDispatcher.h b/orc-rt/include/orc-rt/QueueingTaskDispatcher.h
@@ -0,0 +1,57 @@
+//===------------------ QueueingTaskDispatcher.h ----------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// QueueingTaskDispatcher class.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef ORC_RT_QUEUEINGTASKDISPATCHER_H
+#define ORC_RT_QUEUEINGTASKDISPATCHER_H
+
+#include "orc-rt/TaskDispatcher.h"
+
+#include <deque>
+#include <memory>
+#include <mutex>
+
+namespace orc_rt {
+
+/// A TaskDispatcher implementation that puts tasks in a queue to be run.
+/// QueueingTaskDispatcher provides direct access to the queue, allowing
+/// clients to decide how to run tasks. It is intended for use on systems
+/// where threads are not available, and for unit tests.
+/// For most uses of the ORC runtime, use of QueueingTaskDispatcher is strongly
+/// discouraged, and alternatives like ThreadPoolTaskDispatcher are preferred.
+class QueueingTaskDispatcher : public TaskDispatcher {
+public:
+  void dispatch(std::unique_ptr<Task> T) override;
+  void shutdown() override;
+
+  /// Take a task from the back of the queue. If there are no tasks, returns
+  /// nullptr.
+  std::unique_ptr<Task> pop_back();
+
+  /// Take a task from the front of the queue. If there are no tasks, returns
+  /// nullptr.
+  std::unique_ptr<Task> pop_front();
+
+  /// Run tasks in last-in-first-out order until the queue is empty.
+  void runLIFOUntilEmpty();
+
+  /// Run tasks in first-in-first-out order until the queue is empty.
+  void runFIFOUntilEmpty();
+
+private:
+  std::mutex M;
+  enum { Running, Shutdown } State = Running;
+  std::deque<std::unique_ptr<Task>> Tasks;
+};
+
+} // namespace orc_rt
+
+#endif // ORC_RT_QUEUEINGTASKDISPATCHER_H
diff --git a/orc-rt/lib/executor/CMakeLists.txt b/orc-rt/lib/executor/CMakeLists.txt
@@ -1,6 +1,7 @@
 set(files
   AllocAction.cpp
   Error.cpp
+  QueueingTaskDispatcher.cpp
   ResourceManager.cpp
   RTTI.cpp
   Session.cpp
diff --git a/orc-rt/lib/executor/QueueingTaskDispatcher.cpp b/orc-rt/lib/executor/QueueingTaskDispatcher.cpp
@@ -0,0 +1,64 @@
+//===- QueueingTaskDispatcher.cpp -----------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// Contains the implementation of APIs in the orc-rt/QueueingTaskDispatcher.h
+// header.
+//
+//===----------------------------------------------------------------------===//
+
+#include "orc-rt/QueueingTaskDispatcher.h"
+
+#include <cassert>
+
+namespace orc_rt {
+
+void QueueingTaskDispatcher::dispatch(std::unique_ptr<Task> T) {
+  std::scoped_lock<std::mutex> Lock(M);
+  if (State == Running)
+    Tasks.push_back(std::move(T));
+}
+
+void QueueingTaskDispatcher::shutdown() {
+  std::deque<std::unique_ptr<Task>> ResidualTasks;
+  {
+    std::scoped_lock<std::mutex> Lock(M);
+    State = Shutdown;
+    ResidualTasks = std::move(Tasks);
+  }
+  // ResidualTask destruction can run Task destructors outside the lock.
+}
+
+std::unique_ptr<Task> QueueingTaskDispatcher::pop_back() {
+  std::scoped_lock<std::mutex> Lock(M);
+  if (Tasks.empty())
+    return nullptr;
+  auto T = std::move(Tasks.back());
+  Tasks.pop_back();
+  return T;
+}
+
+std::unique_ptr<Task> QueueingTaskDispatcher::pop_front() {
+  std::scoped_lock<std::mutex> Lock(M);
+  if (Tasks.empty())
+    return nullptr;
+  auto T = std::move(Tasks.front());
+  Tasks.pop_front();
+  return T;
+}
+
+void QueueingTaskDispatcher::runLIFOUntilEmpty() {
+  while (auto T = pop_back())
+    T->run();
+}
+
+void QueueingTaskDispatcher::runFIFOUntilEmpty() {
+  while (auto T = pop_front())
+    T->run();
+}
+
+} // namespace orc_rt
diff --git a/orc-rt/unittests/CMakeLists.txt b/orc-rt/unittests/CMakeLists.txt
@@ -23,6 +23,7 @@ add_orc_rt_unittest(CoreTests
   IntervalSetTest.cpp
   MathTest.cpp
   MemoryFlagsTest.cpp
+  QueueingTaskDispatcherTest.cpp
   RTTITest.cpp
   ScopeExitTest.cpp
   SessionTest.cpp
diff --git a/orc-rt/unittests/QueueingTaskDispatcherTest.cpp b/orc-rt/unittests/QueueingTaskDispatcherTest.cpp
