gdb/python/lib/gdb/xmethod.py

   1 # Python side of the support for xmethods.
   2 # Copyright (C) 2013-2025 Free Software Foundation, Inc.
   3
   4 # This program is free software; you can redistribute it and/or modify
   5 # it under the terms of the GNU General Public License as published by
   6 # the Free Software Foundation; either version 3 of the License, or
   7 # (at your option) any later version.
   8 #
   9 # This program is distributed in the hope that it will be useful,
  10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 # GNU General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU General Public License
  15 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 """Utilities for defining xmethods"""
  18
  19 import re
  20
  21 import gdb
  22
  23
  24 class XMethod(object):
  25     """Base class (or a template) for an xmethod description.
  26
  27     Currently, the description requires only the 'name' and 'enabled'
  28     attributes.  Description objects are managed by 'XMethodMatcher'
  29     objects (see below).  Note that this is only a template for the
  30     interface of the XMethodMatcher.methods objects.  One could use
  31     this class or choose to use an object which supports this exact same
  32     interface.  Also, an XMethodMatcher can choose not use it 'methods'
  33     attribute.  In such cases this class (or an equivalent) is not used.
  34
  35     Attributes:
  36         name: The name of the xmethod.
  37         enabled: A boolean indicating if the xmethod is enabled.
  38     """
  39
  40     def __init__(self, name):
  41         self.name = name
  42         self.enabled = True
  43
  44
  45 class XMethodMatcher(object):
  46     """Abstract base class for matching an xmethod.
  47
  48     When looking for xmethods, GDB invokes the `match' method of a
  49     registered xmethod matcher to match the object type and method name.
  50     The `match' method in concrete classes derived from this class should
  51     return an `XMethodWorker' object, or a list of `XMethodWorker'
  52     objects if there is a match (see below for 'XMethodWorker' class).
  53
  54     Attributes:
  55         name: The name of the matcher.
  56         enabled: A boolean indicating if the matcher is enabled.
  57         methods: A sequence of objects of type 'XMethod', or objects
  58             which have at least the attributes of an 'XMethod' object.
  59             This list is used by the 'enable'/'disable'/'info' commands to
  60             enable/disable/list the xmethods registered with GDB.  See
  61             the 'match' method below to know how this sequence is used.
  62             This attribute is None if the matcher chooses not have any
  63             xmethods managed by it.
  64     """
  65
  66     def __init__(self, name):
  67         """
  68         Args:
  69             name: An identifying name for the xmethod or the group of
  70                   xmethods returned by the `match' method.
  71         """
  72         self.name = name
  73         self.enabled = True
  74         self.methods = None
  75
  76     def match(self, class_type, method_name):
  77         """Match class type and method name.
  78
  79         In derived classes, it should return an XMethodWorker object, or a
  80         sequence of 'XMethodWorker' objects.  Only those xmethod workers
  81         whose corresponding 'XMethod' descriptor object is enabled should be
  82         returned.
  83
  84         Args:
  85             class_type: The class type (gdb.Type object) to match.
  86             method_name: The name (string) of the method to match.
  87         """
  88         raise NotImplementedError("XMethodMatcher match")
  89
  90
  91 class XMethodWorker(object):
  92     """Base class for all xmethod workers defined in Python.
  93
  94     An xmethod worker is an object which matches the method arguments, and
  95     invokes the method when GDB wants it to.  Internally, GDB first invokes the
  96     'get_arg_types' method to perform overload resolution.  If GDB selects to
  97     invoke this Python xmethod, then it invokes it via the overridden
  98     '__call__' method.  The 'get_result_type' method is used to implement
  99     'ptype' on the xmethod.
 100
 101     Derived classes should override the 'get_arg_types', 'get_result_type'
 102     and '__call__' methods.
 103     """
 104
 105     def get_arg_types(self):
 106         """Return arguments types of an xmethod.
 107
 108         A sequence of gdb.Type objects corresponding to the arguments of the
 109         xmethod are returned.  If the xmethod takes no arguments, then 'None'
 110         or an empty sequence is returned.  If the xmethod takes only a single
 111         argument, then a gdb.Type object or a sequence with a single gdb.Type
 112         element is returned.
 113         """
 114         raise NotImplementedError("XMethodWorker get_arg_types")
 115
 116     def get_result_type(self, *args):
 117         """Return the type of the result of the xmethod.
 118
 119         Args:
 120             args: Arguments to the method.  Each element of the tuple is a
 121                 gdb.Value object.  The first element is the 'this' pointer
 122                 value.  These are the same arguments passed to '__call__'.
 123
 124         Returns:
 125             A gdb.Type object representing the type of the result of the
 126             xmethod.
 127         """
 128         raise NotImplementedError("XMethodWorker get_result_type")
 129
 130     def __call__(self, *args):
 131         """Invoke the xmethod.
 132
 133         Args:
 134             args: Arguments to the method.  Each element of the tuple is a
 135                 gdb.Value object.  The first element is the 'this' pointer
 136                 value.
 137
 138         Returns:
 139             A gdb.Value corresponding to the value returned by the xmethod.
 140             Returns 'None' if the method does not return anything.
 141         """
 142         raise NotImplementedError("XMethodWorker __call__")
 143
 144
 145 class SimpleXMethodMatcher(XMethodMatcher):
 146     """A utility class to implement simple xmethod mathers and workers.
 147
 148     See the __init__ method below for information on how instances of this
 149     class can be used.
 150
 151     For simple classes and methods, one can choose to use this class.  For
 152     complex xmethods, which need to replace/implement template methods on
 153     possibly template classes, one should implement their own xmethod
 154     matchers and workers.  See py-xmethods.py in testsuite/gdb.python
 155     directory of the GDB source tree for examples.
 156     """
 157
 158     class SimpleXMethodWorker(XMethodWorker):
 159         def __init__(self, method_function, arg_types):
 160             self._arg_types = arg_types
 161             self._method_function = method_function
 162
 163         def get_arg_types(self):
 164             return self._arg_types
 165
 166         def __call__(self, *args):
 167             return self._method_function(*args)
 168
 169     def __init__(
 170         self, name, class_matcher, method_matcher, method_function, *arg_types
 171     ):
 172         """
 173         Args:
 174             name: Name of the xmethod matcher.
 175             class_matcher: A regular expression used to match the name of the
 176                 class whose method this xmethod is implementing/replacing.
 177             method_matcher: A regular expression used to match the name of the
 178                 method this xmethod is implementing/replacing.
 179             method_function: A Python callable which would be called via the
 180                 'invoke' method of the worker returned by the objects of this
 181                 class.  This callable should accept the object (*this) as the
 182                 first argument followed by the rest of the arguments to the
 183                 method. All arguments to this function should be gdb.Value
 184                 objects.
 185             arg_types: The gdb.Type objects corresponding to the arguments that
 186                 this xmethod takes. It can be None, or an empty sequence,
 187                 or a single gdb.Type object, or a sequence of gdb.Type objects.
 188         """
 189         XMethodMatcher.__init__(self, name)
 190         assert callable(method_function), (
 191             "The 'method_function' argument to 'SimpleXMethodMatcher' "
 192             "__init__ method should be a callable."
 193         )
 194         self._method_function = method_function
 195         self._class_matcher = class_matcher
 196         self._method_matcher = method_matcher
 197         self._arg_types = arg_types
 198
 199     def match(self, class_type, method_name):
 200         cm = re.match(self._class_matcher, str(class_type.unqualified().tag))
 201         mm = re.match(self._method_matcher, method_name)
 202         if cm and mm:
 203             return SimpleXMethodMatcher.SimpleXMethodWorker(
 204                 self._method_function, self._arg_types
 205             )
 206
 207
 208 # A helper function for register_xmethod_matcher which returns an error
 209 # object if MATCHER is not having the requisite attributes in the proper
 210 # format.
 211
 212
 213 def _validate_xmethod_matcher(matcher):
 214     if not hasattr(matcher, "match"):
 215         return TypeError("Xmethod matcher is missing method: match")
 216     if not hasattr(matcher, "name"):
 217         return TypeError("Xmethod matcher is missing attribute: name")
 218     if not hasattr(matcher, "enabled"):
 219         return TypeError("Xmethod matcher is missing attribute: enabled")
 220     if not isinstance(matcher.name, str):
 221         return TypeError("Attribute 'name' of xmethod matcher is not a " "string")
 222     if matcher.name.find(";") >= 0:
 223         return ValueError("Xmethod matcher name cannot contain ';' in it")
 224
 225
 226 # A helper function for register_xmethod_matcher which looks up an
 227 # xmethod matcher with NAME in LOCUS.  Returns the index of the xmethod
 228 # matcher in 'xmethods' sequence attribute of the LOCUS.  If NAME is not
 229 # found in LOCUS, then -1 is returned.
 230
 231
 232 def _lookup_xmethod_matcher(locus, name):
 233     for i in range(0, len(locus.xmethods)):
 234         if locus.xmethods[i].name == name:
 235             return i
 236     return -1
 237
 238
 239 def register_xmethod_matcher(locus, matcher, replace=False):
 240     """Registers a xmethod matcher MATCHER with a LOCUS.
 241
 242     Arguments:
 243         locus: The locus in which the xmethods should be registered.
 244             It can be 'None' to indicate that the xmethods should be
 245             registered globally. Or, it could be a gdb.Objfile or a
 246             gdb.Progspace object in which the xmethods should be
 247             registered.
 248         matcher: The xmethod matcher to register with the LOCUS.  It
 249             should be an instance of 'XMethodMatcher' class.
 250         replace: If True, replace any existing xmethod matcher with the
 251             same name in the locus.  Otherwise, if a matcher with the same name
 252             exists in the locus, raise an exception.
 253     """
 254     err = _validate_xmethod_matcher(matcher)
 255     if err:
 256         raise err
 257     if not locus:
 258         locus = gdb
 259     if locus == gdb:
 260         locus_name = "global"
 261     else:
 262         locus_name = locus.filename
 263     index = _lookup_xmethod_matcher(locus, matcher.name)
 264     if index >= 0:
 265         if replace:
 266             del locus.xmethods[index]
 267         else:
 268             raise RuntimeError(
 269                 "Xmethod matcher already registered with {}: {}".format(
 270                     locus_name, matcher.name
 271                 )
 272             )
 273     if gdb.parameter("verbose"):
 274         gdb.write(
 275             "Registering xmethod matcher '{}' with '{}' ...\n".format(
 276                 locus_name, matcher.name
 277             )
 278         )
 279     locus.xmethods.insert(0, matcher)