Create SBStatisticsOptions API

Summary:
We can't take away or change a previously available public API function.
To avoid future changes, we intruduce an option type that we can extend without modifying existing APIs.

Author: kusmour

lldb/include/lldb/API/LLDB.h

@@ -56,6 +56,7 @@
 #include "lldb/API/SBReproducer.h"
 #include "lldb/API/SBSection.h"
 #include "lldb/API/SBSourceManager.h"
+#include "lldb/API/SBStatisticsOptions.h"
 #include "lldb/API/SBStream.h"
 #include "lldb/API/SBStringList.h"
 #include "lldb/API/SBStructuredData.h"

lldb/include/lldb/API/SBDefines.h

@@ -99,6 +99,7 @@ class LLDB_API SBReproducer;
 class LLDB_API SBScriptObject;
 class LLDB_API SBSection;
 class LLDB_API SBSourceManager;
+class LLDB_API SBStatisticsOptions;
 class LLDB_API SBStream;
 class LLDB_API SBStringList;
 class LLDB_API SBStructuredData;

lldb/include/lldb/API/SBStatisticsOptions.h

@@ -0,0 +1,31 @@
+//===-- SBStatisticsOptions.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_SBSTATISTICSOPTIONS_H
+#define LLDB_API_SBSTATISTICSOPTIONS_H
+
+#include "lldb/API/SBDefines.h"
+
+namespace lldb {
+
+class LLDB_API SBStatisticsOptions {
+public:
+  SBStatisticsOptions();
+  SBStatisticsOptions(const lldb::SBStatisticsOptions &rhs);
+  ~SBStatisticsOptions();
+
+  const SBStatisticsOptions &operator=(const lldb::SBStatisticsOptions &rhs);
+
+  void SetSummaryOnly(bool b);
+  lldb_private::StatisticsOptions GetStatisticsOptions();
+
+private:
+  std::unique_ptr<lldb_private::StatisticsOptions> m_opaque_up;
+};
+} // namespace lldb
+#endif // LLDB_API_SBSTATISTICSOPTIONS_H

lldb/include/lldb/API/SBTarget.h

@@ -17,6 +17,7 @@
 #include "lldb/API/SBFileSpec.h"
 #include "lldb/API/SBFileSpecList.h"
 #include "lldb/API/SBLaunchInfo.h"
+#include "lldb/API/SBStatisticsOptions.h"
 #include "lldb/API/SBSymbolContextList.h"
 #include "lldb/API/SBType.h"
 #include "lldb/API/SBValue.h"
@@ -86,13 +87,18 @@ class LLDB_API SBTarget {
 
   /// Returns a dump of the collected statistics.
   ///
-  /// \param[in] summary_only
-  ///   If true, only report high level summary statistics without
-  ///   targets/modules/breakpoints etc.. details.
+  /// \return
+  ///     A SBStructuredData with the statistics collected.
+  lldb::SBStructuredData GetStatistics();
+
+  /// Returns a dump of the collected statistics.
+  ///
+  /// \param[in] options
+  ///   An objects object that contains all options for the statistics dumping.
   ///
   /// \return
   ///     A SBStructuredData with the statistics collected.
-  lldb::SBStructuredData GetStatistics(bool summary_only = false);
+  lldb::SBStructuredData GetStatistics(SBStatisticsOptions options);
 
   /// Return the platform object associated with the target.
   ///

lldb/include/lldb/Target/Statistics.h

@@ -130,6 +130,10 @@ struct ConstStringStats {
   ConstString::MemoryStats stats = ConstString::GetMemoryStats();
 };
 
+struct StatisticsOptions {
+  bool summary_only = false;
+};
+
 /// A class that represents statistics for a since lldb_private::Target.
 class TargetStats {
 public:
@@ -177,8 +181,9 @@ class DebuggerStats {
   ///
   /// \return
   ///     Returns a JSON value that contains all target metrics.
-  static llvm::json::Value ReportStatistics(Debugger &debugger, Target *target,
-                                            bool summary_only = false);
+  static llvm::json::Value
+  ReportStatistics(Debugger &debugger, Target *target,
+                   const lldb_private::StatisticsOptions &options);
 
 protected:
   // Collecting stats can be set to true to collect stats that are expensive

lldb/include/lldb/Target/Target.h

@@ -1599,7 +1599,7 @@ class Target : public std::enable_shared_from_this<Target>,
   ///
   /// \return
   ///     Returns a JSON value that contains all target metrics.
-  llvm::json::Value ReportStatistics(bool summary_only = false);
+  llvm::json::Value ReportStatistics(const lldb_private::StatisticsOptions &options);
 
   TargetStats &GetStatistics() { return m_stats; }
 

lldb/include/lldb/lldb-forward.h

@@ -298,6 +298,7 @@ struct CompilerContext;
 struct LineEntry;
 struct PropertyDefinition;
 struct ScriptSummaryFormat;
+struct StatisticsOptions;
 struct StringSummaryFormat;
 template <unsigned N> class StreamBuffer;
 

lldb/source/API/CMakeLists.txt

@@ -69,6 +69,7 @@ add_lldb_library(liblldb SHARED ${option_framework}
   SBScriptObject.cpp
   SBSection.cpp
   SBSourceManager.cpp
+  SBStatisticsOptions.cpp
   SBStream.cpp
   SBStringList.cpp
   SBStructuredData.cpp

lldb/source/API/SBStatisticsOptions.cpp

@@ -0,0 +1,46 @@
+//===-- SBStatisticsOptions.cpp -------------------------------------------===//
+//
+// 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/SBStatisticsOptions.h"
+#include "lldb/Target/Statistics.h"
+#include "lldb/Utility/Instrumentation.h"
+
+#include "Utils.h"
+
+using namespace lldb;
+using namespace lldb_private;
+
+SBStatisticsOptions::SBStatisticsOptions()
+    : m_opaque_up(new StatisticsOptions()) {
+  LLDB_INSTRUMENT_VA(this);
+}
+
+SBStatisticsOptions::SBStatisticsOptions(const SBStatisticsOptions &rhs) {
+  LLDB_INSTRUMENT_VA(this, rhs);
+
+  m_opaque_up = clone(rhs.m_opaque_up);
+}
+
+SBStatisticsOptions::~SBStatisticsOptions() = default;
+
+const SBStatisticsOptions &
+SBStatisticsOptions::operator=(const SBStatisticsOptions &rhs) {
+  LLDB_INSTRUMENT_VA(this, rhs);
+
+  if (this != &rhs)
+    m_opaque_up = clone(rhs.m_opaque_up);
+  return *this;
+}
+
+void SBStatisticsOptions::SetSummaryOnly(bool b) {
+  m_opaque_up->summary_only = b;
+}
+
+lldb_private::StatisticsOptions SBStatisticsOptions::GetStatisticsOptions() {
+  return *m_opaque_up;
+}

lldb/source/API/SBTarget.cpp

@@ -197,7 +197,14 @@ SBDebugger SBTarget::GetDebugger() const {
   return debugger;
 }
 
-SBStructuredData SBTarget::GetStatistics(bool summary_only) {
+SBStructuredData SBTarget::GetStatistics() {
+   LLDB_INSTRUMENT_VA(this);
+  SBStatisticsOptions options;
+  options.SetSummaryOnly(false);
+  return GetStatistics(options);
+}
+
+SBStructuredData SBTarget::GetStatistics(SBStatisticsOptions options) {
   LLDB_INSTRUMENT_VA(this);
 
   SBStructuredData data;
@@ -207,7 +214,7 @@ SBStructuredData SBTarget::GetStatistics(bool summary_only) {
   std::string json_str =
       llvm::formatv(
           "{0:2}", DebuggerStats::ReportStatistics(
-                       target_sp->GetDebugger(), target_sp.get(), summary_only))
+                       target_sp->GetDebugger(), target_sp.get(), options.GetStatisticsOptions()))
           .str();
   data.m_impl_up->SetObjectSP(StructuredData::ParseJSON(json_str));
   return data;

lldb/source/Commands/CommandObjectStats.cpp

@@ -93,6 +93,12 @@ class CommandObjectStatsDump : public CommandObjectParsed {
       return llvm::ArrayRef(g_statistics_dump_options);
     }
 
+    StatisticsOptions GetStatisticsOptions() {
+      StatisticsOptions options;
+      options.summary_only = m_summary_only;
+      return options;
+    }
+
     bool m_all_targets = false;
     bool m_summary_only = false;
   };
@@ -114,8 +120,8 @@ class CommandObjectStatsDump : public CommandObjectParsed {
       target = m_exe_ctx.GetTargetPtr();
 
     result.AppendMessageWithFormatv(
-        "{0:2}", DebuggerStats::ReportStatistics(GetDebugger(), target,
-                                                 m_options.m_summary_only));
+        "{0:2}", DebuggerStats::ReportStatistics(
+                     GetDebugger(), target, m_options.GetStatisticsOptions()));
     result.SetStatus(eReturnStatusSuccessFinishResult);
   }
 

lldb/source/Target/Statistics.cpp

@@ -216,9 +216,12 @@ void TargetStats::IncreaseSourceMapDeduceCount() {
 
 bool DebuggerStats::g_collecting_stats = false;
 
-llvm::json::Value DebuggerStats::ReportStatistics(Debugger &debugger,
-                                                  Target *target,
-                                                  bool summary_only) {
+llvm::json::Value DebuggerStats::ReportStatistics(
+    Debugger &debugger, Target *target,
+    const lldb_private::StatisticsOptions &options) {
+
+  bool summary_only = options.summary_only;
+
   json::Array json_targets;
   json::Array json_modules;
   double symtab_parse_time = 0.0;
@@ -338,10 +341,10 @@ llvm::json::Value DebuggerStats::ReportStatistics(Debugger &debugger,
   };
 
   if (target) {
-    json_targets.emplace_back(target->ReportStatistics(summary_only));
+    json_targets.emplace_back(target->ReportStatistics(options));
   } else {
     for (const auto &target : debugger.GetTargetList().Targets())
-      json_targets.emplace_back(target->ReportStatistics(summary_only));
+      json_targets.emplace_back(target->ReportStatistics(options));
   }
   global_stats.try_emplace("targets", std::move(json_targets));
 

lldb/source/Target/Target.cpp

@@ -4962,6 +4962,6 @@ std::recursive_mutex &Target::GetAPIMutex() {
 }
 
 /// Get metrics associated with this target in JSON format.
-llvm::json::Value Target::ReportStatistics(bool summary_only) {
-  return m_stats.ToJSON(*this, summary_only);
+llvm::json::Value Target::ReportStatistics(const lldb_private::StatisticsOptions &options) {
+  return m_stats.ToJSON(*this, options.summary_only);
 }