[lldb][Formatters] Add --pointer-match-depth option to type summary add command. (#138209)

Currently, the type `T`'s summary formatter will be matched for `T`,
`T*`, `T**` and so on. This is unexpected in many data formatters. Such
unhandled cases could cause the data formatter to crash. An example
would be the lldb's built-in data formatter for `std::optional`:
```
$ cat main.cpp
#include <optional>

int main() {
  std::optional<int> o_null;
  auto po_null = &o_null;
  auto ppo_null = &po_null;
  auto pppo_null = &ppo_null;
  return 0;
}
$ clang++ -g main.cpp && lldb -o "b 8" -o "r" -o "v pppo_null"
[lldb crash]
```

This change adds an options `--pointer-match-depth` to `type summary
add` command to allow users to specify how many layer of pointers can be
dereferenced at most when matching a summary formatter of type `T`, as
Jim suggested
[here](#124048).
By default, this option has value 1 which means summary formatter for
`T` could also be used for `T*` but not `T**` nor beyond. This option is
no-op when `--skip-pointers` is set as well.

I didn't add such option for `type synthetic add`, `type format add`,
`type filter add`, because it useful for those command. Instead, they
all have the pointer match depth of 1. When printing a type `T*`, lldb
never print the children of `T` even if there is a synthetic formatter
registered for `T`.

Author: ZequanWu

lldb/docs/use/variable.rst

@@ -366,6 +366,20 @@ The command to obtain the output shown in the example is:
 Initially, we will focus on summary strings, and then describe the Python
 binding mechanism.
 
+Summary Format Matching On Pointers
+----------------------
+
+A summary formatter for a type ``T`` might or might not be appropriate to use
+for pointers to that type. If the formatter is only appropriate for the type and
+not its pointers, use the ``-p`` option to restrict it to match SBValues of type
+``T``. If you want the formatter to also match pointers to the type, you can use
+the ``-d`` option to specify how many pointer layers the formatter should match.
+The default value is 1, so if you don't specify ``-p`` or ``-d``, your formatter
+will be used on SBValues of type ``T`` and ``T*``. If you want to also match
+``T**`` set ``-d`` to 2, etc. In all cases, the SBValue passed to the summary
+formatter will be the matched ValueObject. lldb doesn't dereference the matched
+value down to the SBValue of type ``T`` before passing it to your formatter.
+
 Summary Strings
 ---------------
 

lldb/include/lldb/API/SBTypeSummary.h

@@ -109,6 +109,10 @@ class SBTypeSummary {
 
   void SetFunctionCode(const char *data);
 
+  uint32_t GetPtrMatchDepth();
+
+  void SetPtrMatchDepth(uint32_t ptr_match_depth);
+
   uint32_t GetOptions();
 
   void SetOptions(uint32_t);

lldb/include/lldb/DataFormatters/FormatClasses.h

@@ -76,9 +76,10 @@ class FormattersMatchCandidate {
 
   FormattersMatchCandidate(ConstString name,
                            ScriptInterpreter *script_interpreter, TypeImpl type,
-                           Flags flags)
+                           Flags flags, uint32_t ptr_stripped_depth = 0)
       : m_type_name(name), m_script_interpreter(script_interpreter),
-        m_type(type), m_flags(flags) {}
+        m_type(type), m_flags(flags), m_ptr_stripped_depth(ptr_stripped_depth) {
+  }
 
   ~FormattersMatchCandidate() = default;
 
@@ -96,6 +97,8 @@ class FormattersMatchCandidate {
 
   bool DidStripTypedef() const { return m_flags.stripped_typedef; }
 
+  uint32_t GetPtrStrippedDepth() const { return m_ptr_stripped_depth; }
+
   template <class Formatter>
   bool IsMatch(const std::shared_ptr<Formatter> &formatter_sp) const {
     if (!formatter_sp)
@@ -104,6 +107,8 @@ class FormattersMatchCandidate {
       return false;
     if (formatter_sp->SkipsPointers() && DidStripPointer())
       return false;
+    if (formatter_sp->GetPtrMatchDepth() < GetPtrStrippedDepth())
+      return false;
     if (formatter_sp->SkipsReferences() && DidStripReference())
       return false;
     return true;
@@ -116,6 +121,7 @@ class FormattersMatchCandidate {
   ScriptInterpreter *m_script_interpreter;
   TypeImpl m_type;
   Flags m_flags;
+  uint32_t m_ptr_stripped_depth;
 };
 
 typedef std::vector<FormattersMatchCandidate> FormattersMatchVector;

lldb/include/lldb/DataFormatters/FormatManager.h

@@ -180,7 +180,8 @@ class FormatManager : public IFormatChangeListener {
                                  lldb::DynamicValueType use_dynamic,
                                  FormattersMatchVector &entries,
                                  FormattersMatchCandidate::Flags current_flags,
-                                 bool root_level = false);
+                                 bool root_level = false,
+                                 uint32_t ptr_stripped_depth = 0);
 
   std::atomic<uint32_t> m_last_revision;
   FormatCache m_format_cache;

lldb/include/lldb/DataFormatters/FormattersContainer.h

@@ -193,12 +193,10 @@ template <typename ValueType> class FormattersContainer {
   bool Get(const FormattersMatchVector &candidates, ValueSP &entry) {
     for (const FormattersMatchCandidate &candidate : candidates) {
       if (Get(candidate, entry)) {
-        if (candidate.IsMatch(entry) == false) {
-          entry.reset();
-          continue;
-        } else {
+        if (candidate.IsMatch(entry))
           return true;
-        }
+        entry.reset();
+        continue;
       }
     }
     return false;

lldb/include/lldb/DataFormatters/TypeFormat.h

@@ -133,6 +133,10 @@ class TypeFormatImpl {
 
   void SetOptions(uint32_t value) { m_flags.SetValue(value); }
 
+  uint32_t GetPtrMatchDepth() { return m_ptr_match_depth; }
+
+  void SetPtrMatchDepth(uint32_t value) { m_ptr_match_depth = value; }
+
   uint32_t &GetRevision() { return m_my_revision; }
 
   enum class Type { eTypeUnknown, eTypeFormat, eTypeEnum };
@@ -150,6 +154,7 @@ class TypeFormatImpl {
 protected:
   Flags m_flags;
   uint32_t m_my_revision = 0;
+  uint32_t m_ptr_match_depth = 1;
 
 private:
   TypeFormatImpl(const TypeFormatImpl &) = delete;

lldb/include/lldb/DataFormatters/TypeSummary.h

@@ -253,6 +253,10 @@ class TypeSummaryImpl {
 
   void SetOptions(uint32_t value) { m_flags.SetValue(value); }
 
+  uint32_t GetPtrMatchDepth() { return m_ptr_match_depth; }
+
+  void SetPtrMatchDepth(uint32_t value) { m_ptr_match_depth = value; }
+
   // we are using a ValueObject* instead of a ValueObjectSP because we do not
   // need to hold on to this for extended periods of time and we trust the
   // ValueObject to stay around for as long as it is required for us to
@@ -278,10 +282,12 @@ class TypeSummaryImpl {
   uint32_t m_my_revision = 0;
   Flags m_flags;
 
-  TypeSummaryImpl(Kind kind, const TypeSummaryImpl::Flags &flags);
+  TypeSummaryImpl(Kind kind, const TypeSummaryImpl::Flags &flags,
+                  uint32_t ptr_match_depth = 1);
 
 private:
   Kind m_kind;
+  uint32_t m_ptr_match_depth = 1;
   TypeSummaryImpl(const TypeSummaryImpl &) = delete;
   const TypeSummaryImpl &operator=(const TypeSummaryImpl &) = delete;
 };
@@ -292,7 +298,8 @@ struct StringSummaryFormat : public TypeSummaryImpl {
   FormatEntity::Entry m_format;
   Status m_error;
 
-  StringSummaryFormat(const TypeSummaryImpl::Flags &flags, const char *f);
+  StringSummaryFormat(const TypeSummaryImpl::Flags &flags, const char *f,
+                      uint32_t ptr_match_depth = 1);
 
   ~StringSummaryFormat() override = default;
 
@@ -328,7 +335,8 @@ struct CXXFunctionSummaryFormat : public TypeSummaryImpl {
   std::string m_description;
 
   CXXFunctionSummaryFormat(const TypeSummaryImpl::Flags &flags, Callback impl,
-                           const char *description);
+                           const char *description,
+                           uint32_t ptr_match_depth = 1);
 
   ~CXXFunctionSummaryFormat() override = default;
 
@@ -373,7 +381,8 @@ struct ScriptSummaryFormat : public TypeSummaryImpl {
 
   ScriptSummaryFormat(const TypeSummaryImpl::Flags &flags,
                       const char *function_name,
-                      const char *python_script = nullptr);
+                      const char *python_script = nullptr,
+                      uint32_t ptr_match_depth = 1);
 
   ~ScriptSummaryFormat() override = default;
 

lldb/include/lldb/DataFormatters/TypeSynthetic.h

@@ -273,9 +273,14 @@ class SyntheticChildren {
 
   uint32_t &GetRevision() { return m_my_revision; }
 
+  uint32_t GetPtrMatchDepth() { return m_ptr_match_depth; }
+
+  void SetPtrMatchDepth(uint32_t value) { m_ptr_match_depth = value; }
+
 protected:
   uint32_t m_my_revision = 0;
   Flags m_flags;
+  uint32_t m_ptr_match_depth = 1;
 
 private:
   SyntheticChildren(const SyntheticChildren &) = delete;

lldb/source/API/SBTypeSummary.cpp

@@ -230,6 +230,22 @@ const char *SBTypeSummary::GetData() {
   return nullptr;
 }
 
+uint32_t SBTypeSummary::GetPtrMatchDepth() {
+  LLDB_INSTRUMENT_VA(this);
+
+  if (!IsValid())
+    return 0;
+  return m_opaque_sp->GetPtrMatchDepth();
+}
+
+void SBTypeSummary::SetPtrMatchDepth(uint32_t ptr_match_depth) {
+  LLDB_INSTRUMENT_VA(this);
+
+  if (!IsValid())
+    return;
+  return m_opaque_sp->SetPtrMatchDepth(ptr_match_depth);
+}
+
 uint32_t SBTypeSummary::GetOptions() {
   LLDB_INSTRUMENT_VA(this);
 

lldb/source/Commands/CommandObjectType.cpp

@@ -51,12 +51,13 @@ class ScriptAddOptions {
   FormatterMatchType m_match_type;
   ConstString m_name;
   std::string m_category;
+  uint32_t m_ptr_match_depth;
 
   ScriptAddOptions(const TypeSummaryImpl::Flags &flags,
                    FormatterMatchType match_type, ConstString name,
-                   std::string catg)
+                   std::string catg, uint32_t m_ptr_match_depth)
       : m_flags(flags), m_match_type(match_type), m_name(name),
-        m_category(catg) {}
+        m_category(catg), m_ptr_match_depth(m_ptr_match_depth) {}
 
   typedef std::shared_ptr<ScriptAddOptions> SharedPointer;
 };
@@ -146,6 +147,7 @@ class CommandObjectTypeSummaryAdd : public CommandObjectParsed,
     std::string m_python_function;
     bool m_is_add_script = false;
     std::string m_category;
+    uint32_t m_ptr_match_depth = 1;
   };
 
   CommandOptions m_options;
@@ -211,7 +213,7 @@ class CommandObjectTypeSummaryAdd : public CommandObjectParsed,
                 TypeSummaryImplSP script_format;
                 script_format = std::make_shared<ScriptSummaryFormat>(
                     options->m_flags, funct_name_str.c_str(),
-                    lines.CopyList("    ").c_str());
+                    lines.CopyList("    ").c_str(), options->m_ptr_match_depth);
 
                 Status error;
 
@@ -1178,6 +1180,13 @@ Status CommandObjectTypeSummaryAdd::CommandOptions::SetOptionValue(
   case 'p':
     m_flags.SetSkipPointers(true);
     break;
+  case 'd':
+    if (option_arg.getAsInteger(0, m_ptr_match_depth)) {
+      error = Status::FromErrorStringWithFormat(
+          "invalid integer value for option '%c': %s", short_option,
+          option_arg.data());
+    }
+    break;
   case 'r':
     m_flags.SetSkipReferences(true);
     break;
@@ -1266,7 +1275,8 @@ bool CommandObjectTypeSummaryAdd::Execute_ScriptSummary(
         ("    " + m_options.m_python_function + "(valobj,internal_dict)");
 
     script_format = std::make_shared<ScriptSummaryFormat>(
-        m_options.m_flags, funct_name, code.c_str());
+        m_options.m_flags, funct_name, code.c_str(),
+        m_options.m_ptr_match_depth);
 
     ScriptInterpreter *interpreter = GetDebugger().GetScriptInterpreter();
 
@@ -1300,12 +1310,13 @@ bool CommandObjectTypeSummaryAdd::Execute_ScriptSummary(
     std::string code = "    " + m_options.m_python_script;
 
     script_format = std::make_shared<ScriptSummaryFormat>(
-        m_options.m_flags, funct_name_str.c_str(), code.c_str());
+        m_options.m_flags, funct_name_str.c_str(), code.c_str(),
+        m_options.m_ptr_match_depth);
   } else {
     // Use an IOHandler to grab Python code from the user
     auto options = std::make_unique<ScriptAddOptions>(
         m_options.m_flags, m_options.m_match_type, m_options.m_name,
-        m_options.m_category);
+        m_options.m_category, m_options.m_ptr_match_depth);
 
     for (auto &entry : command.entries()) {
       if (entry.ref().empty()) {
@@ -1380,8 +1391,8 @@ bool CommandObjectTypeSummaryAdd::Execute_StringSummary(
     return false;
   }
 
-  std::unique_ptr<StringSummaryFormat> string_format(
-      new StringSummaryFormat(m_options.m_flags, format_cstr));
+  std::unique_ptr<StringSummaryFormat> string_format(new StringSummaryFormat(
+      m_options.m_flags, format_cstr, m_options.m_ptr_match_depth));
   if (!string_format) {
     result.AppendError("summary creation failed");
     return false;

lldb/source/Commands/Options.td

@@ -1249,6 +1249,10 @@ let Command = "type summary add" in {
     Desc<"Don't show the value, just show the summary, for this type.">;
   def type_summary_add_skip_pointers : Option<"skip-pointers", "p">,
     Desc<"Don't use this format for pointers-to-type objects.">;
+  def type_summary_add_pointer_match_depth : Option<"pointer-match-depth", "d">,
+    Arg<"UnsignedInteger">,
+    Desc<"Specify the maximum pointer depth that this format can be apply to "
+    "(default to 1). It's only effective when --skip-pointers is not set.">;
   def type_summary_add_skip_references : Option<"skip-references", "r">,
     Desc<"Don't use this format for references-to-type objects.">;
   def type_summary_add_regex : Option<"regex", "x">,