[Lldb-commits] [lldb] [LLDB][SBProgress] Add a finalize method (PR #128966)
Jacob Lalonde via lldb-commits
lldb-commits at lists.llvm.org
Thu Feb 27 11:53:11 PST 2025
https://github.com/Jlalond updated https://github.com/llvm/llvm-project/pull/128966
>From 7597ee080abcaaa8b88af316409feb849fb6d7f2 Mon Sep 17 00:00:00 2001
From: Jacob Lalonde <jalalonde at fb.com>
Date: Wed, 26 Feb 2025 15:38:24 -0800
Subject: [PATCH 1/3] Add a finalize method to the sbprogress, with an
associated doc string and a test
---
.../bindings/interface/SBProgressDocstrings.i | 7 +++
lldb/include/lldb/API/SBProgress.h | 5 +++
lldb/source/API/SBProgress.cpp | 10 +++++
.../python_api/sbprogress/TestSBProgress.py | 43 ++++++-------------
4 files changed, 36 insertions(+), 29 deletions(-)
diff --git a/lldb/bindings/interface/SBProgressDocstrings.i b/lldb/bindings/interface/SBProgressDocstrings.i
index 2997fe619fcc7..50648b62411f8 100644
--- a/lldb/bindings/interface/SBProgressDocstrings.i
+++ b/lldb/bindings/interface/SBProgressDocstrings.i
@@ -12,3 +12,10 @@ 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;
+
+%feature("docstring",
+"Explicitly end an SBProgress, this is a utility to send the progressEnd event
+without waiting for your language or language implementations non-deterministic destruction
+of the SBProgress object.
+
+Note once finalized, no further increments will be processed.") lldb::SBProgress::Finalize;
diff --git a/lldb/include/lldb/API/SBProgress.h b/lldb/include/lldb/API/SBProgress.h
index d574d1d2982b9..1558cdc08e080 100644
--- a/lldb/include/lldb/API/SBProgress.h
+++ b/lldb/include/lldb/API/SBProgress.h
@@ -59,6 +59,11 @@ class LLDB_API SBProgress {
void Increment(uint64_t amount, const char *description = nullptr);
+ /// Explicitly finalize an SBProgress, this can be used to terminate a
+ /// progress on command instead of waiting for a garbage collection or other
+ /// finalizer.
+ void Finalize();
+
protected:
lldb_private::Progress &ref() const;
diff --git a/lldb/source/API/SBProgress.cpp b/lldb/source/API/SBProgress.cpp
index 3e548854ab739..9b3f8acc27b00 100644
--- a/lldb/source/API/SBProgress.cpp
+++ b/lldb/source/API/SBProgress.cpp
@@ -40,10 +40,20 @@ SBProgress::~SBProgress() = default;
void SBProgress::Increment(uint64_t amount, const char *description) {
LLDB_INSTRUMENT_VA(amount, description);
+ if (!m_opaque_up)
+ return;
+
std::optional<std::string> description_opt;
if (description && description[0])
description_opt = description;
m_opaque_up->Increment(amount, std::move(description_opt));
}
+void SBProgress::Finalize() {
+ if (!m_opaque_up)
+ return;
+
+ m_opaque_up.reset();
+}
+
lldb_private::Progress &SBProgress::ref() const { return *m_opaque_up; }
diff --git a/lldb/test/API/python_api/sbprogress/TestSBProgress.py b/lldb/test/API/python_api/sbprogress/TestSBProgress.py
index 1b8f01d3e8bb1..b043ce9c4bf89 100644
--- a/lldb/test/API/python_api/sbprogress/TestSBProgress.py
+++ b/lldb/test/API/python_api/sbprogress/TestSBProgress.py
@@ -5,35 +5,6 @@
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.assertIn(expected_string, 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))
-
def test_with_external_bit_set(self):
"""Test SBProgress can handle null events."""
@@ -65,3 +36,17 @@ def test_with_external_bit_set(self):
stream = lldb.SBStream()
event.GetDescription(stream)
self.assertIn("Step 3", stream.GetData())
+
+ def test_progress_finalize(self):
+ """Test SBProgress finalize sends the progressEnd event"""
+
+ progress = lldb.SBProgress("Test SBProgress", "Test finalize", self.dbg)
+ listener = lldb.SBListener("Test listener")
+ broadcaster = self.dbg.GetBroadcaster()
+ broadcaster.AddListener(listener, lldb.eBroadcastBitExternalProgressCategory)
+ event = lldb.SBEvent()
+ progress.Finalize()
+ self.assertTrue(listener.WaitForEvent(5, event))
+ stream = lldb.SBStream()
+ event.GetDescription(stream)
+ self.assertIn("type = end", stream.GetData())
>From 143e4dade36a1c1aadfa0bb50bba6219b3da7edb Mon Sep 17 00:00:00 2001
From: Jacob Lalonde <jalalonde at fb.com>
Date: Wed, 26 Feb 2025 16:44:29 -0800
Subject: [PATCH 2/3] Add a split test case of progress with a total and
without a total ending on finalize
---
lldb/source/API/SBProgress.cpp | 8 +++++---
.../python_api/sbprogress/TestSBProgress.py | 18 +++++++++++++++++-
2 files changed, 22 insertions(+), 4 deletions(-)
diff --git a/lldb/source/API/SBProgress.cpp b/lldb/source/API/SBProgress.cpp
index 9b3f8acc27b00..e3318624c5fd1 100644
--- a/lldb/source/API/SBProgress.cpp
+++ b/lldb/source/API/SBProgress.cpp
@@ -50,9 +50,11 @@ void SBProgress::Increment(uint64_t amount, const char *description) {
}
void SBProgress::Finalize() {
- if (!m_opaque_up)
- return;
-
+ // The lldb_private::Progress object is designed to be RAII and send the end
+ // progress event when it gets destroyed. So force our contained object to be
+ // destroyed and send the progress end event. Clearing this object also allows
+ // all other methods to quickly return without doing any work if they are
+ // called after this method.
m_opaque_up.reset();
}
diff --git a/lldb/test/API/python_api/sbprogress/TestSBProgress.py b/lldb/test/API/python_api/sbprogress/TestSBProgress.py
index b043ce9c4bf89..2a0689a52a185 100644
--- a/lldb/test/API/python_api/sbprogress/TestSBProgress.py
+++ b/lldb/test/API/python_api/sbprogress/TestSBProgress.py
@@ -37,7 +37,7 @@ def test_with_external_bit_set(self):
event.GetDescription(stream)
self.assertIn("Step 3", stream.GetData())
- def test_progress_finalize(self):
+ def test_progress_finalize_non_deterministic_progress(self):
"""Test SBProgress finalize sends the progressEnd event"""
progress = lldb.SBProgress("Test SBProgress", "Test finalize", self.dbg)
@@ -50,3 +50,19 @@ def test_progress_finalize(self):
stream = lldb.SBStream()
event.GetDescription(stream)
self.assertIn("type = end", stream.GetData())
+
+ def test_progress_finalize_deterministic_progress(self):
+ """Test SBProgress finalize sends the progressEnd event"""
+
+ progress = lldb.SBProgress("Test SBProgress", "Test finalize", 13, self.dbg)
+ listener = lldb.SBListener("Test listener")
+ broadcaster = self.dbg.GetBroadcaster()
+ broadcaster.AddListener(listener, lldb.eBroadcastBitExternalProgressCategory)
+ event = lldb.SBEvent()
+ progress.Finalize()
+ self.assertTrue(listener.WaitForEvent(5, event))
+ stream = lldb.SBStream()
+ event.GetDescription(stream)
+ # Note even for progresses with a total, the total isn't
+ # sent in the end message.
+ self.assertIn("type = end", stream.GetData())
>From 213d6856fba13bc0eb2ed5d4a074c4b9cac0571a Mon Sep 17 00:00:00 2001
From: Jacob Lalonde <jalalonde at fb.com>
Date: Thu, 27 Feb 2025 11:36:37 -0800
Subject: [PATCH 3/3] Add docstring about increment
---
lldb/bindings/interface/SBProgressDocstrings.i | 4 ++++
lldb/include/lldb/API/SBProgress.h | 2 +-
2 files changed, 5 insertions(+), 1 deletion(-)
diff --git a/lldb/bindings/interface/SBProgressDocstrings.i b/lldb/bindings/interface/SBProgressDocstrings.i
index 50648b62411f8..8386822887855 100644
--- a/lldb/bindings/interface/SBProgressDocstrings.i
+++ b/lldb/bindings/interface/SBProgressDocstrings.i
@@ -19,3 +19,7 @@ without waiting for your language or language implementations non-deterministic
of the SBProgress object.
Note once finalized, no further increments will be processed.") lldb::SBProgress::Finalize;
+
+%feature("docstring",
+"Increment the progress by a given number of units, optionally with a message. Not all progress events are guaraunteed
+to be sent, but incrementing to the total will always guarauntee a progress end event being sent.") lldb::SBProcess::Increment;
diff --git a/lldb/include/lldb/API/SBProgress.h b/lldb/include/lldb/API/SBProgress.h
index 1558cdc08e080..e5e8196bcaa81 100644
--- a/lldb/include/lldb/API/SBProgress.h
+++ b/lldb/include/lldb/API/SBProgress.h
@@ -61,7 +61,7 @@ class LLDB_API SBProgress {
/// Explicitly finalize an SBProgress, this can be used to terminate a
/// progress on command instead of waiting for a garbage collection or other
- /// finalizer.
+ /// RAII to destroy the contained progress object.
void Finalize();
protected:
More information about the lldb-commits
mailing list