[Lldb-commits] [lldb] [LLDB] Add SBProgress so Python scripts can also report progress (PR #119052)

via lldb-commits lldb-commits at lists.llvm.org
Fri Dec 6 18:43:23 PST 2024 

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-lldb

Author: Jacob Lalonde (Jlalond)

<details>
<summary>Changes</summary>

Recently I've been working on a lot of internal Python tooling, and in certain cases I want to report async to the script over DAP. Progress.h already handles this, so I've exposed Progress via the SB API so Python scripts can also update progress objects.

I actually have no idea how to test this, so I just wrote a [toy command to test it](https://gist.github.com/Jlalond/48d85e75a91f7a137e3142e6a13d0947)

![image](https://github.com/user-attachments/assets/7317cbb8-9145-4fdb-bacf-9864bf50c467)

I also copied the first section of the extensive Progress.h class documentation to the docstrings.

---
Full diff: https://github.com/llvm/llvm-project/pull/119052.diff


8 Files Affected:

- (modified) lldb/bindings/headers.swig (+1) 
- (added) lldb/bindings/interface/SBProgressDocstrings.i (+14) 
- (modified) lldb/bindings/interfaces.swig (+2) 
- (modified) lldb/include/lldb/API/SBDebugger.h (+2-1) 
- (added) lldb/include/lldb/API/SBProgress.h (+56) 
- (modified) lldb/include/lldb/lldb-forward.h (+1) 
- (modified) lldb/source/API/CMakeLists.txt (+1) 
- (added) lldb/source/API/SBProgress.cpp (+34) 


``````````diff
diff --git a/lldb/bindings/headers.swig b/lldb/bindings/headers.swig
index c0dde905f986bd..5e7c54d1eb8393 100644
--- a/lldb/bindings/headers.swig
+++ b/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"
diff --git a/lldb/bindings/interface/SBProgressDocstrings.i b/lldb/bindings/interface/SBProgressDocstrings.i
new file mode 100644
index 00000000000000..016c02432c4117
--- /dev/null
+++ b/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
diff --git a/lldb/bindings/interfaces.swig b/lldb/bindings/interfaces.swig
index 8a6fed95f0b729..08df9a1a8d5392 100644
--- a/lldb/bindings/interfaces.swig
+++ b/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"
diff --git a/lldb/include/lldb/API/SBDebugger.h b/lldb/include/lldb/API/SBDebugger.h
index 1f42ec3cdc7d51..a4c4e11f03dff9 100644
--- a/lldb/include/lldb/API/SBDebugger.h
+++ b/lldb/include/lldb/API/SBDebugger.h
@@ -203,7 +203,7 @@ class LLDB_API SBDebugger {
   lldb::SBCommandInterpreter GetCommandInterpreter();
 
   void HandleCommand(const char *command);
-  
+
   void RequestInterrupt();
   void CancelInterruptRequest();
   bool InterruptRequested();
@@ -513,6 +513,7 @@ class LLDB_API SBDebugger {
   friend class SBPlatform;
   friend class SBTarget;
   friend class SBTrace;
+  friend class SBProgress;
 
   lldb::SBTarget FindTargetWithLLDBProcess(const lldb::ProcessSP &processSP);
 
diff --git a/lldb/include/lldb/API/SBProgress.h b/lldb/include/lldb/API/SBProgress.h
new file mode 100644
index 00000000000000..38f4b4a81f42b7
--- /dev/null
+++ b/lldb/include/lldb/API/SBProgress.h
@@ -0,0 +1,56 @@
+//===-- 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 SB API Wrapper around lldb_private::Progress
+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(const lldb::SBProgress &rhs);
+  ~SBProgress();
+
+  const SBProgress &operator=(const lldb::SBProgress &rhs);
+
+  void Increment(uint64_t amount = 1, 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
diff --git a/lldb/include/lldb/lldb-forward.h b/lldb/include/lldb/lldb-forward.h
index d09edeeccaff1a..fc7456a4b9a32e 100644
--- a/lldb/include/lldb/lldb-forward.h
+++ b/lldb/include/lldb/lldb-forward.h
@@ -233,6 +233,7 @@ class Symtab;
 class SyntheticChildren;
 class SyntheticChildrenFrontEnd;
 class SystemRuntime;
+class Progress;
 class Target;
 class TargetList;
 class TargetProperties;
diff --git a/lldb/source/API/CMakeLists.txt b/lldb/source/API/CMakeLists.txt
index d8308841c05dba..147b30f3b00269 100644
--- a/lldb/source/API/CMakeLists.txt
+++ b/lldb/source/API/CMakeLists.txt
@@ -83,6 +83,7 @@ add_lldb_library(liblldb SHARED ${option_framework}
   SBModule.cpp
   SBModuleSpec.cpp
   SBPlatform.cpp
+  SBProgress.cpp
   SBProcess.cpp
   SBProcessInfo.cpp
   SBProcessInfoList.cpp
diff --git a/lldb/source/API/SBProgress.cpp b/lldb/source/API/SBProgress.cpp
new file mode 100644
index 00000000000000..adfe3c0b865845
--- /dev/null
+++ b/lldb/source/API/SBProgress.cpp
@@ -0,0 +1,34 @@
+//===-- SBProgress.cpp -------------------------------------------*- 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
+//
+//===----------------------------------------------------------------------===//
+
+#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, std::nullopt, debugger.get());
+}
+
+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());
+}
+
+void SBProgress::Increment(uint64_t amount, const char *description) {
+  m_opaque_up->Increment(amount, description);
+}
+
+lldb_private::Progress &SBProgress::ref() const { return *m_opaque_up; }

``````````

</details>


https://github.com/llvm/llvm-project/pull/119052

More information about the lldb-commits mailing list