[lldb/API] Add SBCompileUnit::GetIndexForLineEntry method to SB API

[mib]

Summary

This patch adds a new GetIndexForLineEntry method to the SBCompileUnit
class. As the name suggests, given an SBLineEntry object, this will
return the line entry index within a specific compile unit.

This method can take a exact boolean that will make sure that the
provided line entry matches perfectly another line entry in the compile unit.

rdar://47450887

Signed-off-by: Med Ismail Bennani <[e-mail]>

[jingham]

This needs a doctoring for the API and some test.

lldb/source/API/SBCompileUnit.cpp

86

llvm would prefer an early return here.

94

Why do you have to do this Compare? You already passed exact to FindLineEntry, does FindLineEntry really return line entries that fail your Compare test when exact is passed in as true? That doesn't seem right.

[mib]

lldb/source/API/SBCompileUnit.cpp

94

exact could be false, in which case the line entry index returned by FindLineEntry will be different from the one provided by the user.

But if the user really wants the exact line entry index, we need to compare the returned line entry and the one provided by the user.

[mib]

Addressed @jingham comments:

• Use early returns
• Remove LineEntry::Compare call since it's already handled by CompileUnit::FindLineEntry
• Add docstring

[mib]

I forgot to add the test in the previous diffs --'

[mib]

Address @jingham feedbacks

[jingham]

LGTM

[JDevlieghere]

lldb/include/lldb/API/SBCompileUnit.h

37

How's this different from FindLineEntryIndex? In other words why not make this an FindLineEntryIndex overload? It would be good to document this here (too).

[mib]

Actually, landed this yesterday in a6926d576131c9ad849fef6f1d43134caab5025e

lldb/include/lldb/API/SBCompileUnit.h

37

We already have a line entry but we just want to get the index in the compile unit, so it made sense to have a separate method for this.

[JDevlieghere]

lldb/include/lldb/API/SBCompileUnit.h

37

I was referring to the name. It seems weird to have a few overloads of FindLineEntryIndex and then a totally different function GetIndexForLineEntry. Are they conceptually different enough to have different names? Don't they both return the line entry index?

lldb/bindings/interface/SBCompileUnit.i

public:
     GetFileSpec () const;
 
     uint32_t
     GetNumLineEntries () const;
 
     lldb::SBLineEntry
     GetLineEntryAtIndex (uint32_t idx) const;
 
+    %feature("docstring", "
+     Get the index for a provided line entry in this compile unit.
+
+     @param[in] line_entry
+        The SBLineEntry object for which we are looking for the index.
+
+     @param[in] exact
+        An optional boolean defaulting to false that ensures that the provided
+        line entry has a perfect match in the compile unit.
+
+     @return
+        The index of the user-provided line entry. UINT32_MAX if the line entry
+        was not found in the compile unit.") GetIndexForLineEntry;
+    uint32_t
+    GetIndexForLineEntry (lldb::SBLineEntry &line_entry, bool exact = false) const;
+
     uint32_t
     FindLineEntryIndex (uint32_t start_idx,
                         uint32_t line,
                         lldb::SBFileSpec *inline_file_spec) const;
 
     uint32_t
     FindLineEntryIndex (uint32_t start_idx,
                         uint32_t line,

lldb/include/lldb/API/SBCompileUnit.h

public:
   bool IsValid() const;
 
   lldb::SBFileSpec GetFileSpec() const;
 
   uint32_t GetNumLineEntries() const;
 
   lldb::SBLineEntry GetLineEntryAtIndex(uint32_t idx) const;
 
+  uint32_t GetIndexForLineEntry(lldb::SBLineEntry &line_entry,
+                                bool exact = false) const;
+
   uint32_t FindLineEntryIndex(uint32_t start_idx, uint32_t line,
                               lldb::SBFileSpec *inline_file_spec) const;
 
   uint32_t FindLineEntryIndex(uint32_t start_idx, uint32_t line,
                               lldb::SBFileSpec *inline_file_spec,
                               bool exact) const;
 
   SBFileSpec GetSupportFileAtIndex(uint32_t idx) const;

lldb/source/API/SBCompileUnit.cpp

if (line_table) {
       if (line_table->GetLineEntryAtIndex(idx, line_entry))
         sb_line_entry.SetLineEntry(line_entry);
     }
   }
 
   return sb_line_entry;
 }
 
+uint32_t SBCompileUnit::GetIndexForLineEntry(lldb::SBLineEntry &line_entry,
+                                             bool exact) const {
+  LLDB_INSTRUMENT_VA(this, line_entry, exact);
+
+  if (!m_opaque_ptr || !line_entry.IsValid())
+    return UINT32_MAX;
+
+  LineEntry found_line_entry;
+
+  return m_opaque_ptr->FindLineEntry(0, line_entry.GetLine(),
+                                     line_entry.GetFileSpec().get(), exact,
+                                     &line_entry.ref());
+}
+
 uint32_t SBCompileUnit::FindLineEntryIndex(uint32_t start_idx, uint32_t line,
                                            SBFileSpec *inline_file_spec) const {
   LLDB_INSTRUMENT_VA(this, start_idx, line, inline_file_spec);
 
   const bool exact = true;
   return FindLineEntryIndex(start_idx, line, inline_file_spec, exact);
 }
 
 uint32_t SBCompileUnit::FindLineEntryIndex(uint32_t start_idx, uint32_t line,

lldb/test/API/python_api/compile_unit/Makefile

+C_SOURCES := main.c
+
+include Makefile.rules

lldb/test/API/python_api/compile_unit/TestCompileUnitAPI.py

+"""
+Test SBCompileUnit APIs.
+"""
+
+import lldb
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test import lldbutil
+
+
+class CompileUnitAPITestCase(TestBase):
+
+    mydir = TestBase.compute_mydir(__file__)
+
+    def setUp(self):
+        TestBase.setUp(self)
+
+    def test(self):
+        """Exercise some SBCompileUnit APIs."""
+        self.build()
+
+        (target, process, thread, bkpt) = lldbutil.run_to_source_breakpoint(self, 'break here', lldb.SBFileSpec('main.c'))
+        self.assertTrue(target, VALID_TARGET)
+        self.assertTrue(process, PROCESS_IS_VALID)
+        self.assertTrue(bkpt and bkpt.GetNumLocations() == 1,
+                        VALID_BREAKPOINT)
+
+        self.assertTrue(
+            thread.IsValid(),
+            "There should be a thread stopped due to breakpoint condition")
+        frame0 = thread.GetFrameAtIndex(0)
+        line_entry = frame0.GetLineEntry()
+
+        sc_list = target.FindCompileUnits(line_entry.GetFileSpec())
+        self.assertGreater(sc_list.GetSize(), 0)
+
+        main_cu = sc_list.compile_units[0]
+        self.assertTrue(main_cu.IsValid(), "Main executable CU is not valid")
+
+        self.assertEqual(main_cu.GetIndexForLineEntry(line_entry, True),
+                         main_cu.FindLineEntryIndex(0, line_entry.GetLine(),
+                                   line_entry.GetFileSpec(), True))
+
+

lldb/test/API/python_api/compile_unit/main.c

+int a(int);
+int b(int);
+int c(int);
+
+int a(int val) {
+  if (val <= 1)
+    val = b(val);
+  else if (val >= 3)
+    val = c(val);
+
+  return val;
+}
+
+int b(int val) { return c(val); }
+
+int c(int val) {
+  return val + 3; // break here.
+}
+
+int main(int argc, char const *argv[]) {
+  int A1 = a(1); // a(1) -> b(1) -> c(1)
+  int B2 = b(2); // b(2) -> c(2)
+  int A3 = a(3); // a(3) -> c(3)
+  return 0;
+}