[🍒 swift/release/6.1] [LLDB-DAP] Send Progress update message over DAP (#123837)

lldb/bindings/headers.swig

@@ -52,6 +52,7 @@
 #include "lldb/API/SBProcess.h"
 #include "lldb/API/SBProcessInfo.h"
 #include "lldb/API/SBProcessInfoList.h"
+#include "lldb/API/SBProgress.h"
 #include "lldb/API/SBQueue.h"
 #include "lldb/API/SBQueueItem.h"
 #include "lldb/API/SBReproducer.h"

lldb/bindings/interface/SBProgressDocstrings.i

@@ -0,0 +1,14 @@
+%feature("docstring",
+"A Progress indicator helper class.
+
+Any potentially long running sections of code in LLDB should report
+progress so that clients are aware of delays that might appear during
+debugging. Delays commonly include indexing debug information, parsing
+symbol tables for object files, downloading symbols from remote
+repositories, and many more things.
+
+The Progress class helps make sure that progress is correctly reported
+and will always send an initial progress update, updates when
+Progress::Increment() is called, and also will make sure that a progress
+completed update is reported even if the user doesn't explicitly cause one
+to be sent.") lldb::SBProgress;

lldb/bindings/interfaces.swig

@@ -54,6 +54,7 @@
 %include "./interface/SBPlatformDocstrings.i"
 %include "./interface/SBProcessDocstrings.i"
 %include "./interface/SBProcessInfoDocstrings.i"
+%include "./interface/SBProgressDocstrings.i"
 %include "./interface/SBQueueDocstrings.i"
 %include "./interface/SBQueueItemDocstrings.i"
 %include "./interface/SBReproducerDocstrings.i"
@@ -133,6 +134,7 @@
 %include "lldb/API/SBProcess.h"
 %include "lldb/API/SBProcessInfo.h"
 %include "lldb/API/SBProcessInfoList.h"
+%include "lldb/API/SBProgress.h"
 %include "lldb/API/SBQueue.h"
 %include "lldb/API/SBQueueItem.h"
 %include "lldb/API/SBReproducer.h"

lldb/bindings/python/static-binding/lldb.py

@@ -1807,6 +1807,10 @@ def lldb_iter(obj, getsize, getelem):
 
 eBroadcastBitProgressCategory = _lldb.eBroadcastBitProgressCategory
 
+eBroadcastBitExternalProgress = _lldb.eBroadcastBitExternalProgress
+
+eBroadcastBitExternalProgressCategory = _lldb.eBroadcastBitExternalProgressCategory
+
 eSeverityError = _lldb.eSeverityError
 
 eSeverityWarning = _lldb.eSeverityWarning
@@ -4652,6 +4656,10 @@ def disassemble_instructions (insts):
 
     eBroadcastBitProgressCategory = _lldb.SBDebugger_eBroadcastBitProgressCategory
 
+    eBroadcastBitExternalProgress = _lldb.SBDebugger_eBroadcastBitExternalProgress
+
+    eBroadcastBitExternalProgressCategory = _lldb.SBDebugger_eBroadcastBitExternalProgressCategory
+
 
     def __init__(self, *args):
         r"""
@@ -9885,6 +9893,40 @@ def __iter__(self):
 
 # Register SBProcessInfoList in _lldb:
 _lldb.SBProcessInfoList_swigregister(SBProcessInfoList)
+class SBProgress(object):
+    r"""
+    A Progress indicator helper class.
+
+    Any potentially long running sections of code in LLDB should report
+    progress so that clients are aware of delays that might appear during
+    debugging. Delays commonly include indexing debug information, parsing
+    symbol tables for object files, downloading symbols from remote
+    repositories, and many more things.
+
+    The Progress class helps make sure that progress is correctly reported
+    and will always send an initial progress update, updates when
+    Progress::Increment() is called, and also will make sure that a progress
+    completed update is reported even if the user doesn't explicitly cause one
+    to be sent.
+    """
+
+    thisown = property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc="The membership flag")
+    __repr__ = _swig_repr
+
+    def __init__(self, *args):
+        r"""
+        __init__(SBProgress self, char const * title, char const * details, SBDebugger debugger) -> SBProgress
+        __init__(SBProgress self, char const * title, char const * details, uint64_t total_units, SBDebugger debugger) -> SBProgress
+        """
+        _lldb.SBProgress_swiginit(self, _lldb.new_SBProgress(*args))
+    __swig_destroy__ = _lldb.delete_SBProgress
+
+    def Increment(self, amount, description=None):
+        r"""Increment(SBProgress self, uint64_t amount, char const * description=None)"""
+        return _lldb.SBProgress_Increment(self, amount, description)
+
+# Register SBProgress in _lldb:
+_lldb.SBProgress_swigregister(SBProgress)
 class SBQueue(object):
     r"""Represents a libdispatch queue in the process."""
 

lldb/include/lldb/API/SBDebugger.h

@@ -42,12 +42,16 @@ class LLDB_API SBInputReader {
 
 class LLDB_API SBDebugger {
 public:
-  FLAGS_ANONYMOUS_ENUM(){
-      eBroadcastBitProgress = lldb::DebuggerBroadcastBit::eBroadcastBitProgress,
-      eBroadcastBitWarning = lldb::DebuggerBroadcastBit::eBroadcastBitWarning,
-      eBroadcastBitError = lldb::DebuggerBroadcastBit::eBroadcastBitError,
-      eBroadcastBitProgressCategory =
-          lldb::DebuggerBroadcastBit::eBroadcastBitProgressCategory,
+  FLAGS_ANONYMOUS_ENUM() {
+    eBroadcastBitProgress = lldb::DebuggerBroadcastBit::eBroadcastBitProgress,
+    eBroadcastBitWarning = lldb::DebuggerBroadcastBit::eBroadcastBitWarning,
+    eBroadcastBitError = lldb::DebuggerBroadcastBit::eBroadcastBitError,
+    eBroadcastBitProgressCategory =
+        lldb::DebuggerBroadcastBit::eBroadcastBitProgressCategory,
+    eBroadcastBitExternalProgress =
+        lldb::DebuggerBroadcastBit::eBroadcastBitExternalProgress,
+    eBroadcastBitExternalProgressCategory =
+        lldb::DebuggerBroadcastBit::eBroadcastBitExternalProgressCategory,
   };
   SBDebugger();
 
@@ -203,7 +207,7 @@ class LLDB_API SBDebugger {
   lldb::SBCommandInterpreter GetCommandInterpreter();
 
   void HandleCommand(const char *command);
-  
+
   void RequestInterrupt();
   void CancelInterruptRequest();
   bool InterruptRequested();
@@ -512,6 +516,7 @@ class LLDB_API SBDebugger {
   friend class SBPlatform;
   friend class SBTarget;
   friend class SBTrace;
+  friend class SBProgress;
 
   lldb::SBTarget FindTargetWithLLDBProcess(const lldb::ProcessSP &processSP);
 

lldb/include/lldb/API/SBProgress.h

@@ -0,0 +1,66 @@
+//===-- SBProgress.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
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLDB_API_SBPROGRESS_H
+#define LLDB_API_SBPROGRESS_H
+
+#include "lldb/API/SBDebugger.h"
+#include "lldb/API/SBDefines.h"
+
+namespace lldb {
+
+/// A Progress indicator helper class.
+///
+/// Any potentially long running sections of code in LLDB should report
+/// progress so that clients are aware of delays that might appear during
+/// debugging. Delays commonly include indexing debug information, parsing
+/// symbol tables for object files, downloading symbols from remote
+/// repositories, and many more things.
+///
+/// The Progress class helps make sure that progress is correctly reported
+/// and will always send an initial progress update, updates when
+/// Progress::Increment() is called, and also will make sure that a progress
+/// completed update is reported even if the user doesn't explicitly cause one
+/// to be sent.
+class LLDB_API SBProgress {
+public:
+  /// Construct a progress object with a title, details and a given debugger.
+  /// \param title
+  ///   The title of the progress object.
+  /// \param details
+  ///   The details of the progress object.
+  /// \param debugger
+  ///   The debugger for this progress object to report to.
+  SBProgress(const char *title, const char *details, SBDebugger &debugger);
+
+  /// Construct a progress object with a title, details, the total units of work
+  /// to be done, and a given debugger.
+  /// \param title
+  ///   The title of the progress object.
+  /// \param details
+  ///   The details of the progress object.
+  /// \param total_units
+  ///   The total number of units of work to be done.
+  /// \param debugger
+  ///   The debugger for this progress object to report to.
+  SBProgress(const char *title, const char *details, uint64_t total_units,
+             SBDebugger &debugger);
+
+  ~SBProgress();
+
+  void Increment(uint64_t amount, const char *description = nullptr);
+
+protected:
+  lldb_private::Progress &ref() const;
+
+private:
+  std::unique_ptr<lldb_private::Progress> m_opaque_up;
+}; // SBProgress
+} // namespace lldb
+
+#endif // LLDB_API_SBPROGRESS_H

lldb/include/lldb/Core/Progress.h

@@ -10,6 +10,7 @@
 #define LLDB_CORE_PROGRESS_H
 
 #include "lldb/Host/Alarm.h"
+#include "lldb/Utility/Timeout.h"
 #include "lldb/lldb-forward.h"
 #include "lldb/lldb-types.h"
 #include "llvm/ADT/StringMap.h"
@@ -58,6 +59,12 @@ namespace lldb_private {
 
 class Progress {
 public:
+  /// Enum to indicate the origin of a progress event, internal or external.
+  enum class Origin : uint8_t {
+    eInternal = 0,
+    eExternal = 1,
+  };
+
   /// Construct a progress object that will report information.
   ///
   /// The constructor will create a unique progress reporting object and
@@ -81,7 +88,9 @@ class Progress {
   /// progress is to be reported only to specific debuggers.
   Progress(std::string title, std::string details = {},
            std::optional<uint64_t> total = std::nullopt,
-           lldb_private::Debugger *debugger = nullptr);
+           lldb_private::Debugger *debugger = nullptr,
+           Timeout<std::nano> minimum_report_time = std::nullopt,
+           Origin origin = Origin::eInternal);
 
   /// Destroy the progress object.
   ///
@@ -116,26 +125,40 @@ class Progress {
     /// The optional debugger ID to report progress to. If this has no value
     /// then all debuggers will receive this event.
     std::optional<lldb::user_id_t> debugger_id;
+
+    /// The origin of the progress event, wheter it is internal or external.
+    Origin origin;
   };
 
 private:
   void ReportProgress();
   static std::atomic<uint64_t> g_id;
-  /// More specific information about the current file being displayed in the
-  /// report.
-  std::string m_details;
-  /// How much work ([0...m_total]) that has been completed.
-  uint64_t m_completed;
+
   /// Total amount of work, use a std::nullopt in the constructor for non
   /// deterministic progress.
-  uint64_t m_total;
-  std::mutex m_mutex;
-  /// Set to true when progress has been reported where m_completed == m_total
-  /// to ensure that we don't send progress updates after progress has
-  /// completed.
-  bool m_complete = false;
+  const uint64_t m_total;
+
+  // Minimum amount of time between two progress reports.
+  const Timeout<std::nano> m_minimum_report_time;
+
   /// Data needed by the debugger to broadcast a progress event.
-  ProgressData m_progress_data;
+  const ProgressData m_progress_data;
+
+  /// How much work ([0...m_total]) that has been completed.
+  std::atomic<uint64_t> m_completed = 0;
+
+  /// Time (in nanoseconds since epoch) of the last progress report.
+  std::atomic<uint64_t> m_last_report_time_ns;
+
+  /// Guards non-const non-atomic members of the class.
+  std::mutex m_mutex;
+
+  /// More specific information about the current file being displayed in the
+  /// report.
+  std::string m_details;
+
+  /// The "completed" value of the last reported event.
+  std::optional<uint64_t> m_prev_completed;
 };
 
 /// A class used to group progress reports by category. This is done by using a

lldb/include/lldb/lldb-enumerations.h

@@ -1383,6 +1383,8 @@ enum DebuggerBroadcastBit {
   eBroadcastBitError = (1 << 2),
   eBroadcastSymbolChange = (1 << 3),
   eBroadcastBitProgressCategory = (1 << 4),
+  eBroadcastBitExternalProgress = (1 << 5),
+  eBroadcastBitExternalProgressCategory = (1 << 6),
 };
 
 /// Used for expressing severity in logs and diagnostics.

lldb/include/lldb/lldb-forward.h

@@ -230,6 +230,7 @@ class Symtab;
 class SyntheticChildren;
 class SyntheticChildrenFrontEnd;
 class SystemRuntime;
+class Progress;
 class Target;
 class TargetList;
 class TargetProperties;

lldb/source/API/CMakeLists.txt

@@ -93,6 +93,7 @@ add_lldb_library(liblldb SHARED ${option_framework}
   SBModule.cpp
   SBModuleSpec.cpp
   SBPlatform.cpp
+  SBProgress.cpp
   SBProcess.cpp
   SBProcessInfo.cpp
   SBProcessInfoList.cpp

lldb/source/API/SBProgress.cpp

@@ -0,0 +1,43 @@
+//===-- SBProgress.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
+//
+//===----------------------------------------------------------------------===//
+
+#include "lldb/API/SBProgress.h"
+#include "lldb/Core/Progress.h"
+#include "lldb/Utility/Instrumentation.h"
+
+using namespace lldb;
+
+SBProgress::SBProgress(const char *title, const char *details,
+                       SBDebugger &debugger) {
+  LLDB_INSTRUMENT_VA(this, title, details, debugger);
+
+  m_opaque_up = std::make_unique<lldb_private::Progress>(
+      title, details, /*total=*/std::nullopt, debugger.get(),
+      /*minimum_report_time=*/std::nullopt,
+      lldb_private::Progress::Origin::eExternal);
+}
+
+SBProgress::SBProgress(const char *title, const char *details,
+                       uint64_t total_units, SBDebugger &debugger) {
+  LLDB_INSTRUMENT_VA(this, title, details, total_units, debugger);
+
+  m_opaque_up = std::make_unique<lldb_private::Progress>(
+      title, details, total_units, debugger.get(),
+      /*minimum_report_time=*/std::nullopt,
+      lldb_private::Progress::Origin::eExternal);
+}
+
+SBProgress::~SBProgress() = default;
+
+void SBProgress::Increment(uint64_t amount, const char *description) {
+  LLDB_INSTRUMENT_VA(amount, description);
+
+  m_opaque_up->Increment(amount, description);
+}
+
+lldb_private::Progress &SBProgress::ref() const { return *m_opaque_up; }

lldb/source/Core/Debugger.cpp

@@ -2004,7 +2004,8 @@ lldb::thread_result_t Debugger::DefaultEventHandler() {
   listener_sp->StartListeningForEvents(
       &m_broadcaster, lldb::eBroadcastBitProgress | lldb::eBroadcastBitWarning |
                           lldb::eBroadcastBitError |
-                          lldb::eBroadcastSymbolChange);
+                          lldb::eBroadcastSymbolChange |
+                          lldb::eBroadcastBitExternalProgress);
 
   // Let the thread that spawned us know that we have started up and that we
   // are now listening to all required events so no events get missed