diff options
Diffstat (limited to 'share/gdb/python/gdb/xmethod.py')
| -rw-r--r-- | share/gdb/python/gdb/xmethod.py | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/share/gdb/python/gdb/xmethod.py b/share/gdb/python/gdb/xmethod.py new file mode 100644 index 0000000..6acc23c --- /dev/null +++ b/share/gdb/python/gdb/xmethod.py @@ -0,0 +1,275 @@ +# Python side of the support for xmethods. +# Copyright (C) 2013-2015 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. + +"""Utilities for defining xmethods""" + +import gdb +import re +import sys + + +if sys.version_info[0] > 2: + # Python 3 removed basestring and long + basestring = str + long = int + + +class XMethod(object): + """Base class (or a template) for an xmethod description. + + Currently, the description requires only the 'name' and 'enabled' + attributes. Description objects are managed by 'XMethodMatcher' + objects (see below). Note that this is only a template for the + interface of the XMethodMatcher.methods objects. One could use + this class or choose to use an object which supports this exact same + interface. Also, an XMethodMatcher can choose not use it 'methods' + attribute. In such cases this class (or an equivalent) is not used. + + Attributes: + name: The name of the xmethod. + enabled: A boolean indicating if the xmethod is enabled. + """ + + def __init__(self, name): + self.name = name + self.enabled = True + + +class XMethodMatcher(object): + """Abstract base class for matching an xmethod. + + When looking for xmethods, GDB invokes the `match' method of a + registered xmethod matcher to match the object type and method name. + The `match' method in concrete classes derived from this class should + return an `XMethodWorker' object, or a list of `XMethodWorker' + objects if there is a match (see below for 'XMethodWorker' class). + + Attributes: + name: The name of the matcher. + enabled: A boolean indicating if the matcher is enabled. + methods: A sequence of objects of type 'XMethod', or objects + which have at least the attributes of an 'XMethod' object. + This list is used by the 'enable'/'disable'/'info' commands to + enable/disable/list the xmethods registered with GDB. See + the 'match' method below to know how this sequence is used. + This attribute is None if the matcher chooses not have any + xmethods managed by it. + """ + + def __init__(self, name): + """ + Args: + name: An identifying name for the xmethod or the group of + xmethods returned by the `match' method. + """ + self.name = name + self.enabled = True + self.methods = None + + def match(self, class_type, method_name): + """Match class type and method name. + + In derived classes, it should return an XMethodWorker object, or a + sequence of 'XMethodWorker' objects. Only those xmethod workers + whose corresponding 'XMethod' descriptor object is enabled should be + returned. + + Args: + class_type: The class type (gdb.Type object) to match. + method_name: The name (string) of the method to match. + """ + raise NotImplementedError("XMethodMatcher match") + + +class XMethodWorker(object): + """Base class for all xmethod workers defined in Python. + + An xmethod worker is an object which matches the method arguments, and + invokes the method when GDB wants it to. Internally, GDB first invokes the + 'get_arg_types' method to perform overload resolution. If GDB selects to + invoke this Python xmethod, then it invokes it via the overridden + '__call__' method. The 'get_result_type' method is used to implement + 'ptype' on the xmethod. + + Derived classes should override the 'get_arg_types', 'get_result_type' + and '__call__' methods. + """ + + def get_arg_types(self): + """Return arguments types of an xmethod. + + A sequence of gdb.Type objects corresponding to the arguments of the + xmethod are returned. If the xmethod takes no arguments, then 'None' + or an empty sequence is returned. If the xmethod takes only a single + argument, then a gdb.Type object or a sequence with a single gdb.Type + element is returned. + """ + raise NotImplementedError("XMethodWorker get_arg_types") + + def get_result_type(self, *args): + """Return the type of the result of the xmethod. + + Args: + args: Arguments to the method. Each element of the tuple is a + gdb.Value object. The first element is the 'this' pointer + value. These are the same arguments passed to '__call__'. + + Returns: + A gdb.Type object representing the type of the result of the + xmethod. + """ + raise NotImplementedError("XMethodWorker get_result_type") + + def __call__(self, *args): + """Invoke the xmethod. + + Args: + args: Arguments to the method. Each element of the tuple is a + gdb.Value object. The first element is the 'this' pointer + value. + + Returns: + A gdb.Value corresponding to the value returned by the xmethod. + Returns 'None' if the method does not return anything. + """ + raise NotImplementedError("XMethodWorker __call__") + + +class SimpleXMethodMatcher(XMethodMatcher): + """A utility class to implement simple xmethod mathers and workers. + + See the __init__ method below for information on how instances of this + class can be used. + + For simple classes and methods, one can choose to use this class. For + complex xmethods, which need to replace/implement template methods on + possibly template classes, one should implement their own xmethod + matchers and workers. See py-xmethods.py in testsuite/gdb.python + directory of the GDB source tree for examples. + """ + + class SimpleXMethodWorker(XMethodWorker): + def __init__(self, method_function, arg_types): + self._arg_types = arg_types + self._method_function = method_function + + def get_arg_types(self): + return self._arg_types + + def __call__(self, *args): + return self._method_function(*args) + + + def __init__(self, name, class_matcher, method_matcher, method_function, + *arg_types): + """ + Args: + name: Name of the xmethod matcher. + class_matcher: A regular expression used to match the name of the + class whose method this xmethod is implementing/replacing. + method_matcher: A regular expression used to match the name of the + method this xmethod is implementing/replacing. + method_function: A Python callable which would be called via the + 'invoke' method of the worker returned by the objects of this + class. This callable should accept the object (*this) as the + first argument followed by the rest of the arguments to the + method. All arguments to this function should be gdb.Value + objects. + arg_types: The gdb.Type objects corresponding to the arguments that + this xmethod takes. It can be None, or an empty sequence, + or a single gdb.Type object, or a sequence of gdb.Type objects. + """ + XMethodMatcher.__init__(self, name) + assert callable(method_function), ( + "The 'method_function' argument to 'SimpleXMethodMatcher' " + "__init__ method should be a callable.") + self._method_function = method_function + self._class_matcher = class_matcher + self._method_matcher = method_matcher + self._arg_types = arg_types + + def match(self, class_type, method_name): + cm = re.match(self._class_matcher, str(class_type.unqualified().tag)) + mm = re.match(self._method_matcher, method_name) + if cm and mm: + return SimpleXMethodMatcher.SimpleXMethodWorker( + self._method_function, self._arg_types) + + +# A helper function for register_xmethod_matcher which returns an error +# object if MATCHER is not having the requisite attributes in the proper +# format. + +def _validate_xmethod_matcher(matcher): + if not hasattr(matcher, "match"): + return TypeError("Xmethod matcher is missing method: match") + if not hasattr(matcher, "name"): + return TypeError("Xmethod matcher is missing attribute: name") + if not hasattr(matcher, "enabled"): + return TypeError("Xmethod matcher is missing attribute: enabled") + if not isinstance(matcher.name, basestring): + return TypeError("Attribute 'name' of xmethod matcher is not a " + "string") + if matcher.name.find(";") >= 0: + return ValueError("Xmethod matcher name cannot contain ';' in it") + + +# A helper function for register_xmethod_matcher which looks up an +# xmethod matcher with NAME in LOCUS. Returns the index of the xmethod +# matcher in 'xmethods' sequence attribute of the LOCUS. If NAME is not +# found in LOCUS, then -1 is returned. + +def _lookup_xmethod_matcher(locus, name): + for i in range(0, len(locus.xmethods)): + if locus.xmethods[i].name == name: + return i + return -1 + + +def register_xmethod_matcher(locus, matcher, replace=False): + """Registers a xmethod matcher MATCHER with a LOCUS. + + Arguments: + locus: The locus in which the xmethods should be registered. + It can be 'None' to indicate that the xmethods should be + registered globally. Or, it could be a gdb.Objfile or a + gdb.Progspace object in which the xmethods should be + registered. + matcher: The xmethod matcher to register with the LOCUS. It + should be an instance of 'XMethodMatcher' class. + replace: If True, replace any existing xmethod matcher with the + same name in the locus. Otherwise, if a matcher with the same name + exists in the locus, raise an exception. + """ + err = _validate_xmethod_matcher(matcher) + if err: + raise err + if not locus: + locus = gdb + if locus == gdb: + locus_name = "global" + else: + locus_name = locus.filename + index = _lookup_xmethod_matcher(locus, matcher.name) + if index >= 0: + if replace: + del locus.xmethods[index] + else: + raise RuntimeError("Xmethod matcher already registered with " + "%s: %s" % (locus_name, matcher.name)) + if gdb.parameter("verbose"): + gdb.write("Registering xmethod matcher '%s' with %s' ...\n") + locus.xmethods.insert(0, matcher) |