[Lldb-commits] [lldb] [LLDB] Add SBProgress so Python scripts can also report progress (PR #119052)
Jacob Lalonde via lldb-commits
lldb-commits at lists.llvm.org
Wed Jan 8 11:31:39 PST 2025
https://github.com/Jlalond updated https://github.com/llvm/llvm-project/pull/119052
>From d28dedabaeb6bdc763e8226e7d669ff4eba66d50 Mon Sep 17 00:00:00 2001
From: Jacob Lalonde <jalalonde at fb.com>
Date: Fri, 6 Dec 2024 18:17:44 -0800
Subject: [PATCH 1/4] Add SBPRogress class to enable commands to async report
to lldb-dap their progress
---
lldb/bindings/headers.swig | 1 +
.../bindings/interface/SBProgressDocstrings.i | 14 +++++
lldb/bindings/interfaces.swig | 2 +
lldb/include/lldb/API/SBDebugger.h | 3 +-
lldb/include/lldb/API/SBProgress.h | 56 +++++++++++++++++++
lldb/include/lldb/lldb-forward.h | 1 +
lldb/source/API/CMakeLists.txt | 1 +
lldb/source/API/SBProgress.cpp | 34 +++++++++++
8 files changed, 111 insertions(+), 1 deletion(-)
create mode 100644 lldb/bindings/interface/SBProgressDocstrings.i
create mode 100644 lldb/include/lldb/API/SBProgress.h
create mode 100644 lldb/source/API/SBProgress.cpp
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 787bd040dd15bb..eb371e33c4951c 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();
@@ -517,6 +517,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; }
>From 956c600347333f961edf01e7754b527f9a9f56d9 Mon Sep 17 00:00:00 2001
From: Jacob Lalonde <jalalonde at fb.com>
Date: Mon, 9 Dec 2024 10:14:03 -0800
Subject: [PATCH 2/4] Add dtor, amend Jonas's feedback on docstrings and
formatting
---
lldb/bindings/interface/SBProgressDocstrings.i | 2 +-
lldb/include/lldb/API/SBProgress.h | 18 +++++++++++++++---
lldb/source/API/SBProgress.cpp | 15 +++++++++++----
3 files changed, 27 insertions(+), 8 deletions(-)
diff --git a/lldb/bindings/interface/SBProgressDocstrings.i b/lldb/bindings/interface/SBProgressDocstrings.i
index 016c02432c4117..2997fe619fcc7a 100644
--- a/lldb/bindings/interface/SBProgressDocstrings.i
+++ b/lldb/bindings/interface/SBProgressDocstrings.i
@@ -11,4 +11,4 @@ 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
+to be sent.") lldb::SBProgress;
diff --git a/lldb/include/lldb/API/SBProgress.h b/lldb/include/lldb/API/SBProgress.h
index 38f4b4a81f42b7..a60d1f3ee567ac 100644
--- a/lldb/include/lldb/API/SBProgress.h
+++ b/lldb/include/lldb/API/SBProgress.h
@@ -14,7 +14,19 @@
namespace lldb {
-/// A SB API Wrapper around lldb_private::Progress
+/// 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.
@@ -38,12 +50,12 @@ class LLDB_API SBProgress {
/// 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);
+ void Increment(uint64_t amount, const char *description = nullptr);
protected:
lldb_private::Progress &ref() const;
diff --git a/lldb/source/API/SBProgress.cpp b/lldb/source/API/SBProgress.cpp
index adfe3c0b865845..8d522d849973a7 100644
--- a/lldb/source/API/SBProgress.cpp
+++ b/lldb/source/API/SBProgress.cpp
@@ -1,5 +1,4 @@
-//===-- SBProgress.cpp -------------------------------------------*- C++
-//-*-===//
+//===-- 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.
@@ -11,23 +10,31 @@
#include "lldb/Core/Progress.h"
#include "lldb/Utility/Instrumentation.h"
+#include "Utils.h"
+
using namespace lldb;
SBProgress::SBProgress(const char *title, const char *details,
SBDebugger &debugger) {
- LLDB_INSTRUMENT_VA(this, title, details, 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)
+ LLDB_INSTRUMENT_VA(this, title, details, total_units, debugger);
+
m_opaque_up = std::make_unique<lldb_private::Progress>(
title, details, total_units, debugger.get());
}
+SBProgress::~SBProgress() = default;
+
void SBProgress::Increment(uint64_t amount, const char *description) {
+ LLDB_INSTRUMENT_VA(amount, description);
+
m_opaque_up->Increment(amount, description);
}
>From 2d56e1ddb5d244eaf0c85f3d1cd24483a21de40d Mon Sep 17 00:00:00 2001
From: Jacob Lalonde <jalalonde at fb.com>
Date: Wed, 8 Jan 2025 10:53:14 -0800
Subject: [PATCH 3/4] Rebase and refactor SBProgress, add positive and negative
test cases
---
lldb/source/API/SBProgress.cpp | 10 +++---
.../python_api/sbprogress/TestSBProgress.py | 36 +++++++++++++++++++
2 files changed, 42 insertions(+), 4 deletions(-)
create mode 100644 lldb/test/API/python_api/sbprogress/TestSBProgress.py
diff --git a/lldb/source/API/SBProgress.cpp b/lldb/source/API/SBProgress.cpp
index 8d522d849973a7..d6ed5f0d15fc94 100644
--- a/lldb/source/API/SBProgress.cpp
+++ b/lldb/source/API/SBProgress.cpp
@@ -10,8 +10,6 @@
#include "lldb/Core/Progress.h"
#include "lldb/Utility/Instrumentation.h"
-#include "Utils.h"
-
using namespace lldb;
SBProgress::SBProgress(const char *title, const char *details,
@@ -19,7 +17,9 @@ SBProgress::SBProgress(const char *title, const char *details,
LLDB_INSTRUMENT_VA(this, title, details, debugger);
m_opaque_up = std::make_unique<lldb_private::Progress>(
- title, details, std::nullopt, debugger.get());
+ 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,
@@ -27,7 +27,9 @@ SBProgress::SBProgress(const char *title, const char *details,
LLDB_INSTRUMENT_VA(this, title, details, total_units, debugger);
m_opaque_up = std::make_unique<lldb_private::Progress>(
- title, details, total_units, debugger.get());
+ title, details, total_units, debugger.get(),
+ /*minimum_report_time=*/std::nullopt,
+ lldb_private::Progress::Origin::eExternal);
}
SBProgress::~SBProgress() = default;
diff --git a/lldb/test/API/python_api/sbprogress/TestSBProgress.py b/lldb/test/API/python_api/sbprogress/TestSBProgress.py
new file mode 100644
index 00000000000000..105b81028f8b06
--- /dev/null
+++ b/lldb/test/API/python_api/sbprogress/TestSBProgress.py
@@ -0,0 +1,36 @@
+"""Test the SBProgress API."""
+
+import lldb
+from lldbsuite.test.lldbtest import *
+
+
+class SBProgressTestCase(TestBase):
+
+ def test_with_external_bit_set(self):
+ """Test SBProgress events are listened to when the external bit is set."""
+
+ progress = lldb.SBProgress("Test SBProgress", "Test progress", self.dbg)
+ listener = lldb.SBListener("Test listener")
+ broadcaster = self.dbg.GetBroadcaster()
+ broadcaster.AddListener(listener, lldb.eBroadcastBitExternalProgress)
+ event = lldb.SBEvent()
+
+ expected_string = "Test progress first increment"
+ progress.Increment(1, expected_string)
+ self.assertTrue(listener.PeekAtNextEvent(event))
+ stream = lldb.SBStream()
+ event.GetDescription(stream)
+ self.assertTrue(expected_string in stream.GetData())
+
+ def test_without_external_bit_set(self):
+ """Test SBProgress events are not listened to on the internal progress bit."""
+
+ progress = lldb.SBProgress("Test SBProgress", "Test progress", self.dbg)
+ listener = lldb.SBListener("Test listener")
+ broadcaster = self.dbg.GetBroadcaster()
+ broadcaster.AddListener(listener, lldb.eBroadcastBitProgress)
+ event = lldb.SBEvent()
+
+ expected_string = "Test progress first increment"
+ progress.Increment(1, expected_string)
+ self.assertFalse(listener.PeekAtNextEvent(event))
>From 61d323b88c0e433ff96d8653fd3d997bcdabc2e8 Mon Sep 17 00:00:00 2001
From: Jacob Lalonde <jalalonde at fb.com>
Date: Wed, 8 Jan 2025 11:26:39 -0800
Subject: [PATCH 4/4] Update debugger to listen to external progress events by
default
---
lldb/source/Core/Debugger.cpp | 3 ++-
lldb/test/API/python_api/sbprogress/TestSBProgress.py | 1 -
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/lldb/source/Core/Debugger.cpp b/lldb/source/Core/Debugger.cpp
index 6ceb209269c9e7..2df2aeb20aa26a 100644
--- a/lldb/source/Core/Debugger.cpp
+++ b/lldb/source/Core/Debugger.cpp
@@ -1952,7 +1952,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
diff --git a/lldb/test/API/python_api/sbprogress/TestSBProgress.py b/lldb/test/API/python_api/sbprogress/TestSBProgress.py
index 105b81028f8b06..4d688336313482 100644
--- a/lldb/test/API/python_api/sbprogress/TestSBProgress.py
+++ b/lldb/test/API/python_api/sbprogress/TestSBProgress.py
@@ -5,7 +5,6 @@
class SBProgressTestCase(TestBase):
-
def test_with_external_bit_set(self):
"""Test SBProgress events are listened to when the external bit is set."""
More information about the lldb-commits
mailing list