[lldb] Add `source cache dump` and `source cache clear` subcommand

[JDevlieghere]

Summary

Add two new source subcommands: source cache dump and source cache clear. As the name implies the first one dumps the source cache while the later clears the cache.

This patch was motivated by a handful of (internal) bug reports related to sources not being available. Right now those issues can be hard to diagnose. The new commands give users, as well as us as developers, more insight into and control over the source cache.

[jasonmolenda]

LGTM

lldb/source/Commands/CommandObjectSource.cpp

1208

Do you want to split this across two lines? I don't think there should be a newline here.

1227

I don't think the newline is necessary/should be here.

1266

Maybe we can make this less accurate and easier to understand. like "Commands for examining source files in the current process".

lldb/source/Core/SourceManager.cpp

738

m/d/Y would be dope tho

[JDevlieghere]

lldb/source/Commands/CommandObjectSource.cpp

1266

But that wouldn't just be less accurate, it would be wrong. The current cache is shared across targets and processes belonging to the same debugger.

lldb/source/Core/SourceManager.cpp

738

🇺🇸

lldb/include/lldb/Core/Debugger.h

 /// \class Debugger Debugger.h "lldb/Core/Debugger.h"
 /// A class to manage flag bits.
 ///
 /// Provides a global root objects for the debugger core.
 
 class Debugger : public std::enable_shared_from_this<Debugger>,
                  public UserID,
                  public Properties {
-  friend class SourceManager; // For GetSourceFileCache.
-
 public:
   /// Broadcaster event bits definitions.
   enum {
     eBroadcastBitProgress = (1 << 0),
     eBroadcastBitWarning = (1 << 1),
     eBroadcastBitError = (1 << 2),
     eBroadcastSymbolChange = (1 << 3),
   };
public:
   /// Manually stop the debugger's default event handler.
   void StopEventHandlerThread();
 
   /// Force flushing the process's pending stdout and stderr to the debugger's
   /// asynchronous stdout and stderr streams.
   void FlushProcessOutput(Process &process, bool flush_stdout,
                           bool flush_stderr);
 
+  SourceManager::SourceFileCache &GetSourceFileCache() {
+    return m_source_file_cache;
+  }
+
 protected:
   friend class CommandInterpreter;
   friend class REPL;
   friend class Progress;
 
   /// Report progress events.
   ///
   /// Progress events will be delivered to any debuggers that have listeners
protected:
 
   void HandleProgressEvent(const lldb::EventSP &event_sp);
 
   void HandleDiagnosticEvent(const lldb::EventSP &event_sp);
 
   // Ensures two threads don't attempt to flush process output in parallel.
   std::mutex m_output_flush_mutex;
 
-  SourceManager::SourceFileCache &GetSourceFileCache() {
-    return m_source_file_cache;
-  }
-
   void InstanceInitialize();
 
   // these should never be NULL
   lldb::FileSP m_input_file_sp;
   lldb::StreamFileSP m_output_stream_sp;
   lldb::StreamFileSP m_error_stream_sp;
 
   /// Used for shadowing the input file when capturing a reproducer.

lldb/include/lldb/Core/SourceManager.h

public:
     uint32_t GetSourceMapModificationID() const { return m_source_map_mod_id; }
 
     const char *PeekLineData(uint32_t line);
 
     uint32_t GetLineLength(uint32_t line, bool include_newline_chars);
 
     uint32_t GetNumLines();
 
+    llvm::sys::TimePoint<> GetTimestamp() const { return m_mod_time; }
+
   protected:
     bool CalculateLineOffsets(uint32_t line = UINT32_MAX);
 
     FileSpec m_file_spec_orig; // The original file spec that was used (can be
                                // different from m_file_spec)
     FileSpec m_file_spec; // The actually file spec being used (if the target
                           // has source mappings, this might be different from
                           // m_file_spec_orig)
public:
     ~SourceFileCache() = default;
 
     void AddSourceFile(const FileSP &file_sp);
     FileSP FindSourceFile(const FileSpec &file_spec) const;
 
     // Removes all elements from the cache.
     void Clear() { m_file_cache.clear(); }
 
+    void Dump(Stream &stream) const;
+
   protected:
     typedef std::map<FileSpec, FileSP> FileCache;
     FileCache m_file_cache;
   };
 
   // Constructors and Destructors
   // A source manager can be made with a non-null target, in which case it can
   // use the path remappings to find

lldb/source/Commands/CommandObjectSource.cpp

const SymbolContextList *GetBreakpointLocations() {
     return nullptr;
   }
 
   CommandOptions m_options;
   FileLineResolver m_breakpoint_locations;
   std::string m_reverse_name;
 };
 
+class CommandObjectSourceCacheDump : public CommandObjectParsed {
+public:
+  CommandObjectSourceCacheDump(CommandInterpreter &interpreter)
+      : CommandObjectParsed(interpreter, "source cache dump",
+                            "Dump the state of the source code cache. Intended "
+                            "to be used for debugging LLDB itself.",
+                            nullptr) {}
+
+  ~CommandObjectSourceCacheDump() override = default;
+
+protected:
+  bool DoExecute(Args &command, CommandReturnObject &result) override {
+    SourceManager::SourceFileCache &cache = GetDebugger().GetSourceFileCache();
+    cache.Dump(result.GetOutputStream());
+    result.SetStatus(eReturnStatusSuccessFinishResult);
+    return result.Succeeded();
+  }
+};
+
+class CommandObjectSourceCacheClear : public CommandObjectParsed {
+public:
+  CommandObjectSourceCacheClear(CommandInterpreter &interpreter)
+      : CommandObjectParsed(interpreter, "source cache clear",
+                            "Clear the source code cache.\n", nullptr) {}
+
+  ~CommandObjectSourceCacheClear() override = default;
+
+protected:
+  bool DoExecute(Args &command, CommandReturnObject &result) override {
+    SourceManager::SourceFileCache &cache = GetDebugger().GetSourceFileCache();
+    cache.Clear();
+    result.SetStatus(eReturnStatusSuccessFinishNoResult);
+    return result.Succeeded();
+  }
+};
+
+class CommandObjectSourceCache : public CommandObjectMultiword {
+public:
+  CommandObjectSourceCache(CommandInterpreter &interpreter)
+      : CommandObjectMultiword(interpreter, "source cache",
+                               "Commands for managing the source code cache.",
+                               "source cache <sub-command>") {
+    LoadSubCommand(
+        "dump", CommandObjectSP(new CommandObjectSourceCacheDump(interpreter)));
+    LoadSubCommand("clear", CommandObjectSP(new CommandObjectSourceCacheClear(
+                                interpreter)));
+  }
+
+  ~CommandObjectSourceCache() override = default;
+
+private:
+  CommandObjectSourceCache(const CommandObjectSourceCache &) = delete;
+  const CommandObjectSourceCache &
+  operator=(const CommandObjectSourceCache &) = delete;
+};
+
 #pragma mark CommandObjectMultiwordSource
 // CommandObjectMultiwordSource
 
 CommandObjectMultiwordSource::CommandObjectMultiwordSource(
     CommandInterpreter &interpreter)
     : CommandObjectMultiword(interpreter, "source",
                              "Commands for examining "
                              "source code described by "
                              "debug information for the "
                              "current target process.",
                              "source <subcommand> [<subcommand-options>]") {
   LoadSubCommand("info",
                  CommandObjectSP(new CommandObjectSourceInfo(interpreter)));
   LoadSubCommand("list",
                  CommandObjectSP(new CommandObjectSourceList(interpreter)));
+  LoadSubCommand("cache",
+                 CommandObjectSP(new CommandObjectSourceCache(interpreter)));
 }
 
 CommandObjectMultiwordSource::~CommandObjectMultiwordSource() = default;

lldb/source/Commands/CommandObjectTarget.cpp

 #pragma mark CommandObjectTargetDumpTypesystem
 
 /// Dumps the TypeSystem of the selected Target.
 class CommandObjectTargetDumpTypesystem : public CommandObjectParsed {
 public:
   CommandObjectTargetDumpTypesystem(CommandInterpreter &interpreter)
       : CommandObjectParsed(
             interpreter, "target dump typesystem",
-            "Dump the state of the target's internal type system.\n"
-            "Intended to be used for debugging LLDB itself.",
+            "Dump the state of the target's internal type system. Intended to "
+            "be used for debugging LLDB itself.",
             nullptr, eCommandRequiresTarget) {}
 
   ~CommandObjectTargetDumpTypesystem() override = default;
 
 protected:
   bool DoExecute(Args &command, CommandReturnObject &result) override {
     // Go over every scratch TypeSystem and dump to the command output.
     for (lldb::TypeSystemSP ts : GetSelectedTarget().GetScratchTypeSystems())

lldb/source/Core/SourceManager.cpp

 SourceManager::FileSP SourceManager::SourceFileCache::FindSourceFile(
     const FileSpec &file_spec) const {
   FileSP file_sp;
   FileCache::const_iterator pos = m_file_cache.find(file_spec);
   if (pos != m_file_cache.end())
     file_sp = pos->second;
   return file_sp;
 }
+
+void SourceManager::SourceFileCache::Dump(Stream &stream) const {
+  stream << "Modification time   Lines    Path\n";
+  stream << "------------------- -------- --------------------------------\n";
+  for (auto &entry : m_file_cache) {
+    if (!entry.second)
+      continue;
+    FileSP file = entry.second;
+    stream.Format("{0:%Y-%m-%d %H:%M:%S} {1,8:d} {2}\n", file->GetTimestamp(),
+                  file->GetNumLines(), entry.first.GetPath());
+  }
+}

lldb/test/API/source-manager/TestSourceManager.py

def test_artificial_source_location(self):
             RUN_SUCCEEDED,
             substrs=[
                 "stop reason = breakpoint",
                 "%s:%d" % (src_file, 0),
                 "Note: this address is compiler-generated code in " "function",
                 "that has no source code associated " "with it.",
             ],
         )
+
+    def test_source_cache_dump_and_clear(self):
+        self.build()
+        exe = self.getBuildArtifact("a.out")
+        self.runCmd("file " + exe, CURRENT_EXECUTABLE_SET)
+        lldbutil.run_break_set_by_file_and_line(
+            self, self.file, self.line, num_expected_locations=1, loc_exact=True
+        )
+        self.runCmd("run", RUN_SUCCEEDED)
+
+        # Make sure the main source file is in the source cache.
+        self.expect(
+            "source cache dump",
+            substrs=["Modification time", "Lines", "Path", " 7", self.file],
+        )
+
+        # Clear the cache.
+        self.expect("source cache clear")
+
+        # Make sure the main source file is no longer in the source cache.
+        self.expect("source cache dump", matching=False, substrs=[self.file])