From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 25735 invoked by alias); 9 Nov 2012 15:05:44 -0000 Mailing-List: contact archer-commits-help@sourceware.org; run by ezmlm Sender: Precedence: bulk List-Post: List-Help: List-Subscribe: Received: (qmail 25702 invoked by uid 9514); 9 Nov 2012 15:05:43 -0000 Date: Fri, 09 Nov 2012 15:05:00 -0000 Message-ID: <20121109150543.25683.qmail@sourceware.org> From: pmuldoon@sourceware.org To: archer-commits@sourceware.org Subject: [SCM] archer-pmuldoon-python-backtrace: First draft of Frame Wrapper API, and beginning of Frame Filter/Wrapper tutorial X-Git-Refname: refs/heads/archer-pmuldoon-python-backtrace X-Git-Reftype: branch X-Git-Oldrev: 21efb231d1aa60794b55884343e4aee5c8e8f22c X-Git-Newrev: d41e9fbcd585abcf20e26ccb449bec2b5359d081 X-SW-Source: 2012-q4/txt/msg00005.txt.bz2 List-Id: The branch, archer-pmuldoon-python-backtrace has been updated via d41e9fbcd585abcf20e26ccb449bec2b5359d081 (commit) from 21efb231d1aa60794b55884343e4aee5c8e8f22c (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email. - Log ----------------------------------------------------------------- commit d41e9fbcd585abcf20e26ccb449bec2b5359d081 Author: Phil Muldoon Date: Fri Nov 9 15:05:02 2012 +0000 First draft of Frame Wrapper API, and beginning of Frame Filter/Wrapper tutorial ----------------------------------------------------------------------- Summary of changes: gdb/doc/gdb.texinfo | 218 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 files changed, 210 insertions(+), 8 deletions(-) First 500 lines of diff: diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 3fd2989..5ce4df4 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -22628,8 +22628,8 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown. * Selecting Pretty-Printers:: How GDB chooses a pretty-printer. * Writing a Pretty-Printer:: Writing a Pretty-Printer. * Frame Filters API:: Filtering and Wrapping Frames. -* Writing a Frame Filter:: Writing a Frame Filter. * Frame Wrapper API:: Wrapping and Decorating Frames. +* Writing a Frame Filter:: Writing a Frame Filter. * Managing Frame Filters:: Management of Frame Filters. * Writing a Frame Wrapper:: Writing a Frame Wrapper. * Inferiors In Python:: Python representation of inferiors (processes) @@ -24140,21 +24140,223 @@ valid operation for frame filters that have decided not to operate on any frames. In this next example, the frame filter operates on all frames, and -uses a @code{Frame Wrapper}. @xref{Frame Wrapper API}, for the API +uses a Frame Wrapper. @xref{Frame Wrapper API}, for the API relating to a @code{Frame Wrapper}. Also, @xref{Writing a Frame -Wrapper}, for a tutorial on writing a @code{Frame Wrapper}. +Wrapper}, for a tutorial on writing a Frame Wrapper. + +@smallexample +class Reverse_Function (BaseFrameWrapper): + + def __init__(self, fobj): + super(Reverse_Function, self).__init__(fobj) + self.fobj = fobj + def function (self): + fname = str (self.fobj.function()) + fname = fname[::-1] + return fname + +class FrameFilter (): + + def __init__ (self): + self.name = "Reverse Filter" + self.priority = 100 + self.enabled = True + gdb.frame_filters [self.name] = self + + def filter (self, frame_iter): + frame_iter = itertools.imap (Reverse_Function, + frame_iter) + return frame_iter +@end smallexample + +There are two objects in this example. A Frame Wrapper and a Frame +Filter. The frame filter in this example uses the Python +@code{itertool} module to operator on the iterator that was passed to +it. @node Frame Wrapper API @subsubsection Wrapping and Decorating Frames. @cindex Frame Wrapper API Frame wrappers are sister objects that decorate frames affected by -frame filters. Frame wrappers are applied by frame filters and -customize the printed content of each frame via an API. A frame -wrapper works on one frame, but a frame wrapper object can be applied -to many different frames. Each frame wrapper dictates the contents of -each frame that is printed by @value{GDBN}. +frame filters. Frame wrappers can only be used in conjunction with +Frame wrappers. + +Frame wrappers are applied by frame filters and customize the printed +content of each frame via an API, defined here. A frame wrapper works +on one frame, but a frame wrapper object can be applied to many +multiple frames. + +@defun FrameWrapper.elided () + +The @code{elided} method groups frames together in a hierarchical +system. An example would be an interpreter call that occurs over many +frames but might be better represented as a group of frames distinct +from the other frames. + +The @code{elide} function must return an iterator that conforms to the +Python iterator protocol, and contains the frames that are being +elided, or @code{None}. Elided frames are indented from normal frames +in a @code{CLI} backtrace, or in the case of @code{GDB/MI} are placed +in the @code{children} field of the eliding frame. + +Note that it is the frame filter that instantiated this frame +wrapper's task to filter out the elided frames from the source +iterator. This will avoid the frame being printed twice. + +If this function returns @code{None}, no frames will be elided. +@end defun + + +@defun FrameWrapper.function () + +This method returns the name of the function in the frame that is to +be printed. + +This method must return a Python string describing the function, or +@code{None}. + +If this function returns a Python None, @value{GDBN} will not print +any data for this field. +@end defun + +@defun FrameWrapper.address () + +This method returns the address of the frame that is to be printed. + +This method must return a Python numeric integer type of sufficient +size to describe the address of the frame, or @code{None}. + +If this function returns a @code{None}, @value{GDBN} will not print +any data for this field. +@end defun + +@defun FrameWrapper.filename () + +This method returns the filename associated with this frame. + +This method must return a Python string containing the filename, and +optionally, the path to the filename of the frame, or @code{None}. + +If this function returns a @code{None}, @value{GDBN} will not print +any data for this field. +@end defun + + +@defun FrameWrapper.line (): + +This method returns the line number associated with the current +position within the function addressed by this frame. + +This method must return a Python integer type, or @code{None}. + +If this function returns a @code{None}, @value{GDBN} will not print +any data for this field. +@end defun + +@defun FrameWrapper.frame_args () + +This method must return a Python iterator that conforms to the Python +iterator protocol. This iterator must contain objects that implement +two methods, described here. + +The object must implement an @code{argument} method which takes no +parameters and must return a @code{gdb.Symbol} or a Python string, and +@code{value} method which takes no parameters and which must return a +@code{gdb.Value}, a Python value, or @code{None}. If the @code{value} +method returns a @code{None}, and the @code{argument} method +returns a @code{gdb.Symbol}, @value{GDBN} will read and print the value +of the @code{gdb.Symbol} automatically. + +A brief example: + +@smallexample +class SymValueWrapper (): + + def __init__(self, symbol, value): + self.sym = symbol + self.val = value + + def value (self): + return self.val + + def symbol (self): + + return self.sym + +class SomeFrameWrapper () +... +... + def frame_args (self): + fvars = [] + fvars.append (SymValueWrapper (``foo'', 42)) + + return iter (fvars) +@end smallexample + +Even if the @code{frame_args} method returns only a single object, it +must be wrapped in an iterator. + +If this function returns a @code{None}, @value{GDBN} will not print +locals for this frame. +@end defun + +@defun FrameWrapper.frame_locals () + +This method must return a Python iterator that conforms to the Python +iterator protocol. This iterator must contain objects that implement +two methods, described here. + +The object must implement an @code{argument} method which takes no +parameters and must return a @code{gdb.Symbol} or a Python string, and +@code{value} method which takes no parameters and which must return a +@code{gdb.Value}, a Python value, or @code{None}. If the @code{value} +method returns a @code{None}, and the @code{argument} method +returns a @code{gdb.Symbol}, @value{GDBN} will read and print the value +of the @code{gdb.Symbol} automatically. + +A brief example: + +@smallexample +class SymValueWrapper (): + + def __init__(self, symbol, value): + self.sym = symbol + self.val = value + + def value (self): + return self.val + + def symbol (self): + + return self.sym + +class SomeFrameWrapper () +... +... + def frame_locals (self): + fvars = [] + fvars.append (SymValueWrapper (``foo'', 42)) + + return iter (fvars) +@end smallexample + +Even if the @code{frame_locals} method returns only a single object, it +must be wrapped in an iterator. + +If this function returns a @code{None}, @value{GDBN} will not print +locals for this frame. + +@end defun + +@defun FrameWrapper.frame (): + +This method must return the underlying @code{gdb.Frame} that this +frame wrapper is wrapping. @value{GDBN} requires the underlying frame +for internal frame information such as architecture so as to determine +how to print certain values in frame printing +@end defun @node Managing Frame Filters @subsubsection Management of Frame Filters. hooks/post-receive -- Repository for Project Archer.