aarch64-linux-gnu-4.9/share/doc/gdb/gdb/Writing-a-Frame-Filter.html - toolchains/linux-x86/gcc - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <!-- Copyright (C) 1988-2015 Free Software Foundation, Inc.

 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with the
 Invariant Sections being "Free Software" and "Free Software Needs
 Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
 and with the Back-Cover Texts as in (a) below.

 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
 this GNU Manual.  Buying copies from GNU Press supports the FSF in
 developing GNU and promoting software freedom." -->
 <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
 <head>
 <title>Debugging with GDB: Writing a Frame Filter</title>

 <meta name="description" content="Debugging with GDB: Writing a Frame Filter">
 <meta name="keywords" content="Debugging with GDB: Writing a Frame Filter">
 <meta name="resource-type" content="document">
 <meta name="distribution" content="global">
 <meta name="Generator" content="makeinfo">
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link href="index.html#Top" rel="start" title="Top">
 <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
 <link href="Python-API.html#Python-API" rel="up" title="Python API">
 <link href="Unwinding-Frames-in-Python.html#Unwinding-Frames-in-Python" rel="next" title="Unwinding Frames in Python">
 <link href="Frame-Decorator-API.html#Frame-Decorator-API" rel="prev" title="Frame Decorator API">
 <style type="text/css">
 <!--
 a.summary-letter {text-decoration: none}
 blockquote.smallquotation {font-size: smaller}
 div.display {margin-left: 3.2em}
 div.example {margin-left: 3.2em}
 div.indentedblock {margin-left: 3.2em}
 div.lisp {margin-left: 3.2em}
 div.smalldisplay {margin-left: 3.2em}
 div.smallexample {margin-left: 3.2em}
 div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
 div.smalllisp {margin-left: 3.2em}
 kbd {font-style:oblique}
 pre.display {font-family: inherit}
 pre.format {font-family: inherit}
 pre.menu-comment {font-family: serif}
 pre.menu-preformatted {font-family: serif}
 pre.smalldisplay {font-family: inherit; font-size: smaller}
 pre.smallexample {font-size: smaller}
 pre.smallformat {font-family: inherit; font-size: smaller}
 pre.smalllisp {font-size: smaller}
 span.nocodebreak {white-space:nowrap}
 span.nolinebreak {white-space:nowrap}
 span.roman {font-family:serif; font-weight:normal}
 span.sansserif {font-family:sans-serif; font-weight:normal}
 ul.no-bullet {list-style: none}
 -->
 </style>


 </head>

 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
 <a name="Writing-a-Frame-Filter"></a>
 <div class="header">
 <p>
 Next: <a href="Unwinding-Frames-in-Python.html#Unwinding-Frames-in-Python" accesskey="n" rel="next">Unwinding Frames in Python</a>, Previous: <a href="Frame-Decorator-API.html#Frame-Decorator-API" accesskey="p" rel="prev">Frame Decorator API</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
 </div>
 <hr>
 <a name="Writing-a-Frame-Filter-1"></a>
 <h4 class="subsubsection">23.2.2.11 Writing a Frame Filter</h4>
 <a name="index-writing-a-frame-filter"></a>

 <p>There are three basic elements that a frame filter must implement: it
 must correctly implement the documented interface (see <a href="Frame-Filter-API.html#Frame-Filter-API">Frame Filter API</a>), it must register itself with <small>GDB</small>, and finally, it must
 decide if it is to work on the data provided by <small>GDB</small>.  In all
 cases, whether it works on the iterator or not, each frame filter must
 return an iterator.  A bare-bones frame filter follows the pattern in
 the following example.
 </p>
 <div class="smallexample">
 <pre class="smallexample">import gdb

 class FrameFilter():

     def __init__(self):
         # Frame filter attribute creation.
         #
         # 'name' is the name of the filter that GDB will display.
         #
         # 'priority' is the priority of the filter relative to other
         # filters.
         #
         # 'enabled' is a boolean that indicates whether this filter is
         # enabled and should be executed.

         self.name = &quot;Foo&quot;
         self.priority = 100
         self.enabled = True

         # Register this frame filter with the global frame_filters
         # dictionary.
         gdb.frame_filters[self.name] = self

     def filter(self, frame_iter):
         # Just return the iterator.
         return frame_iter
 </pre></div>

 <p>The frame filter in the example above implements the three
 requirements for all frame filters.  It implements the API, self
 registers, and makes a decision on the iterator (in this case, it just
 returns the iterator untouched).
 </p>
 <p>The first step is attribute creation and assignment, and as shown in
 the comments the filter assigns the following attributes:  <code>name</code>,
 <code>priority</code> and whether the filter should be enabled with the
 <code>enabled</code> attribute.
 </p>
 <p>The second step is registering the frame filter with the dictionary or
 dictionaries that the frame filter has interest in.  As shown in the
 comments, this filter just registers itself with the global dictionary
 <code>gdb.frame_filters</code>.  As noted earlier, <code>gdb.frame_filters</code>
 is a dictionary that is initialized in the <code>gdb</code> module when
 <small>GDB</small> starts.  What dictionary a filter registers with is an
 important consideration.  Generally, if a filter is specific to a set
 of code, it should be registered either in the <code>objfile</code> or
 <code>progspace</code> dictionaries as they are specific to the program
 currently loaded in <small>GDB</small>.  The global dictionary is always
 present in <small>GDB</small> and is never unloaded.  Any filters registered
 with the global dictionary will exist until <small>GDB</small> exits.  To
 avoid filters that may conflict, it is generally better to register
 frame filters against the dictionaries that more closely align with
 the usage of the filter currently in question.  See <a href="Python-Auto_002dloading.html#Python-Auto_002dloading">Python Auto-loading</a>, for further information on auto-loading Python scripts.
 </p>
 <p><small>GDB</small> takes a hands-off approach to frame filter registration,
 therefore it is the frame filter&rsquo;s responsibility to ensure
 registration has occurred, and that any exceptions are handled
 appropriately.  In particular, you may wish to handle exceptions
 relating to Python dictionary key uniqueness.  It is mandatory that
 the dictionary key is the same as frame filter&rsquo;s <code>name</code>
 attribute.  When a user manages frame filters (see <a href="Frame-Filter-Management.html#Frame-Filter-Management">Frame Filter Management</a>), the names <small>GDB</small> will display are those contained
 in the <code>name</code> attribute.
 </p>
 <p>The final step of this example is the implementation of the
 <code>filter</code> method.  As shown in the example comments, we define the
 <code>filter</code> method and note that the method must take an iterator,
 and also must return an iterator.  In this bare-bones example, the
 frame filter is not very useful as it just returns the iterator
 untouched.  However this is a valid operation for frame filters that
 have the <code>enabled</code> attribute set, but decide not to operate on
 any frames.
 </p>
 <p>In the next example, the frame filter operates on all frames and
 utilizes a frame decorator to perform some work on the frames.
 See <a href="Frame-Decorator-API.html#Frame-Decorator-API">Frame Decorator API</a>, for further information on the frame
 decorator interface.
 </p>
 <p>This example works on inlined frames.  It highlights frames which are
 inlined by tagging them with an &ldquo;[inlined]&rdquo; tag.  By applying a
 frame decorator to all frames with the Python <code>itertools imap</code>
 method, the example defers actions to the frame decorator.  Frame
 decorators are only processed when <small>GDB</small> prints the backtrace.
 </p>
 <p>This introduces a new decision making topic: whether to perform
 decision making operations at the filtering step, or at the printing
 step.  In this example&rsquo;s approach, it does not perform any filtering
 decisions at the filtering step beyond mapping a frame decorator to
 each frame.  This allows the actual decision making to be performed
 when each frame is printed.  This is an important consideration, and
 well worth reflecting upon when designing a frame filter.  An issue
 that frame filters should avoid is unwinding the stack if possible.
 Some stacks can run very deep, into the tens of thousands in some
 cases.  To search every frame to determine if it is inlined ahead of
 time may be too expensive at the filtering step.  The frame filter
 cannot know how many frames it has to iterate over, and it would have
 to iterate through them all.  This ends up duplicating effort as
 <small>GDB</small> performs this iteration when it prints the frames.
 </p>
 <p>In this example decision making can be deferred to the printing step.
 As each frame is printed, the frame decorator can examine each frame
 in turn when <small>GDB</small> iterates.  From a performance viewpoint,
 this is the most appropriate decision to make as it avoids duplicating
 the effort that the printing step would undertake anyway.  Also, if
 there are many frame filters unwinding the stack during filtering, it
 can substantially delay the printing of the backtrace which will
 result in large memory usage, and a poor user experience.
 </p>
 <div class="smallexample">
 <pre class="smallexample">class InlineFilter():

     def __init__(self):
         self.name = &quot;InlinedFrameFilter&quot;
         self.priority = 100
         self.enabled = True
         gdb.frame_filters[self.name] = self

     def filter(self, frame_iter):
         frame_iter = itertools.imap(InlinedFrameDecorator,
                                     frame_iter)
         return frame_iter
 </pre></div>

 <p>This frame filter is somewhat similar to the earlier example, except
 that the <code>filter</code> method applies a frame decorator object called
 <code>InlinedFrameDecorator</code> to each element in the iterator.  The
 <code>imap</code> Python method is light-weight.  It does not proactively
 iterate over the iterator, but rather creates a new iterator which
 wraps the existing one.
 </p>
 <p>Below is the frame decorator for this example.
 </p>
 <div class="smallexample">
 <pre class="smallexample">class InlinedFrameDecorator(FrameDecorator):

     def __init__(self, fobj):
         super(InlinedFrameDecorator, self).__init__(fobj)

     def function(self):
         frame = fobj.inferior_frame()
         name = str(frame.name())

         if frame.type() == gdb.INLINE_FRAME:
             name = name + &quot; [inlined]&quot;

         return name
 </pre></div>

 <p>This frame decorator only defines and overrides the <code>function</code>
 method.  It lets the supplied <code>FrameDecorator</code>, which is shipped
 with <small>GDB</small>, perform the other work associated with printing
 this frame.
 </p>
 <p>The combination of these two objects create this output from a
 backtrace:
 </p>
 <div class="smallexample">
 <pre class="smallexample">#0  0x004004e0 in bar () at inline.c:11
 #1  0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
 #2  0x00400566 in main () at inline.c:31
 </pre></div>

 <p>So in the case of this example, a frame decorator is applied to all
 frames, regardless of whether they may be inlined or not.  As
 <small>GDB</small> iterates over the iterator produced by the frame filters,
 <small>GDB</small> executes each frame decorator which then makes a decision
 on what to print in the <code>function</code> callback.  Using a strategy
 like this is a way to defer decisions on the frame content to printing
 time.
 </p>
 <a name="Eliding-Frames"></a>
 <h4 class="subheading">Eliding Frames</h4>

 <p>It might be that the above example is not desirable for representing
 inlined frames, and a hierarchical approach may be preferred.  If we
 want to hierarchically represent frames, the <code>elided</code> frame
 decorator interface might be preferable.
 </p>
 <p>This example approaches the issue with the <code>elided</code> method.  This
 example is quite long, but very simplistic.  It is out-of-scope for
 this section to write a complete example that comprehensively covers
 all approaches of finding and printing inlined frames.  However, this
 example illustrates the approach an author might use.
 </p>
 <p>This example comprises of three sections.
 </p>
 <div class="smallexample">
 <pre class="smallexample">class InlineFrameFilter():

     def __init__(self):
         self.name = &quot;InlinedFrameFilter&quot;
         self.priority = 100
         self.enabled = True
         gdb.frame_filters[self.name] = self

     def filter(self, frame_iter):
         return ElidingInlineIterator(frame_iter)
 </pre></div>

 <p>This frame filter is very similar to the other examples.  The only
 difference is this frame filter is wrapping the iterator provided to
 it (<code>frame_iter</code>) with a custom iterator called
 <code>ElidingInlineIterator</code>.  This again defers actions to when
 <small>GDB</small> prints the backtrace, as the iterator is not traversed
 until printing.
 </p>
 <p>The iterator for this example is as follows.  It is in this section of
 the example where decisions are made on the content of the backtrace.
 </p>
 <div class="smallexample">
 <pre class="smallexample">class ElidingInlineIterator:
     def __init__(self, ii):
         self.input_iterator = ii

     def __iter__(self):
         return self

     def next(self):
         frame = next(self.input_iterator)

         if frame.inferior_frame().type() != gdb.INLINE_FRAME:
             return frame

         try:
             eliding_frame = next(self.input_iterator)
         except StopIteration:
             return frame
         return ElidingFrameDecorator(eliding_frame, [frame])
 </pre></div>

 <p>This iterator implements the Python iterator protocol.  When the
 <code>next</code> function is called (when <small>GDB</small> prints each frame),
 the iterator checks if this frame decorator, <code>frame</code>, is wrapping
 an inlined frame.  If it is not, it returns the existing frame decorator
 untouched.  If it is wrapping an inlined frame, it assumes that the
 inlined frame was contained within the next oldest frame,
 <code>eliding_frame</code>, which it fetches.  It then creates and returns a
 frame decorator, <code>ElidingFrameDecorator</code>, which contains both the
 elided frame, and the eliding frame.
 </p>
 <div class="smallexample">
 <pre class="smallexample">class ElidingInlineDecorator(FrameDecorator):

     def __init__(self, frame, elided_frames):
         super(ElidingInlineDecorator, self).__init__(frame)
         self.frame = frame
         self.elided_frames = elided_frames

     def elided(self):
         return iter(self.elided_frames)
 </pre></div>

 <p>This frame decorator overrides one function and returns the inlined
 frame in the <code>elided</code> method.  As before it lets
 <code>FrameDecorator</code> do the rest of the work involved in printing
 this frame.  This produces the following output.
 </p>
 <div class="smallexample">
 <pre class="smallexample">#0  0x004004e0 in bar () at inline.c:11
 #2  0x00400529 in main () at inline.c:25
     #1  0x00400529 in max (b=6, a=12) at inline.c:15
 </pre></div>

 <p>In that output, <code>max</code> which has been inlined into <code>main</code> is
 printed hierarchically.  Another approach would be to combine the
 <code>function</code> method, and the <code>elided</code> method to both print a
 marker in the inlined frame, and also show the hierarchical
 relationship.
 </p>
 <hr>
 <div class="header">
 <p>
 Next: <a href="Unwinding-Frames-in-Python.html#Unwinding-Frames-in-Python" accesskey="n" rel="next">Unwinding Frames in Python</a>, Previous: <a href="Frame-Decorator-API.html#Frame-Decorator-API" accesskey="p" rel="prev">Frame Decorator API</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
 </div>


 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<!-- Copyright (C) 1988-2015 Free Software Foundation, Inc.

	Permission is granted to copy, distribute and/or modify this document
	under the terms of the GNU Free Documentation License, Version 1.3 or
	any later version published by the Free Software Foundation; with the
	Invariant Sections being "Free Software" and "Free Software Needs
	Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
	and with the Back-Cover Texts as in (a) below.

	(a) The FSF's Back-Cover Text is: "You are free to copy and modify
	this GNU Manual. Buying copies from GNU Press supports the FSF in
	developing GNU and promoting software freedom." -->
	<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
	<head>
	<title>Debugging with GDB: Writing a Frame Filter</title>

	<meta name="description" content="Debugging with GDB: Writing a Frame Filter">
	<meta name="keywords" content="Debugging with GDB: Writing a Frame Filter">
	<meta name="resource-type" content="document">
	<meta name="distribution" content="global">
	<meta name="Generator" content="makeinfo">
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<link href="index.html#Top" rel="start" title="Top">
	<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
	<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
	<link href="Python-API.html#Python-API" rel="up" title="Python API">
	<link href="Unwinding-Frames-in-Python.html#Unwinding-Frames-in-Python" rel="next" title="Unwinding Frames in Python">
	<link href="Frame-Decorator-API.html#Frame-Decorator-API" rel="prev" title="Frame Decorator API">
	<style type="text/css">
	<!--
	a.summary-letter {text-decoration: none}
	blockquote.smallquotation {font-size: smaller}
	div.display {margin-left: 3.2em}
	div.example {margin-left: 3.2em}
	div.indentedblock {margin-left: 3.2em}
	div.lisp {margin-left: 3.2em}
	div.smalldisplay {margin-left: 3.2em}
	div.smallexample {margin-left: 3.2em}
	div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
	div.smalllisp {margin-left: 3.2em}
	kbd {font-style:oblique}
	pre.display {font-family: inherit}
	pre.format {font-family: inherit}
	pre.menu-comment {font-family: serif}
	pre.menu-preformatted {font-family: serif}
	pre.smalldisplay {font-family: inherit; font-size: smaller}
	pre.smallexample {font-size: smaller}
	pre.smallformat {font-family: inherit; font-size: smaller}
	pre.smalllisp {font-size: smaller}
	span.nocodebreak {white-space:nowrap}
	span.nolinebreak {white-space:nowrap}
	span.roman {font-family:serif; font-weight:normal}
	span.sansserif {font-family:sans-serif; font-weight:normal}
	ul.no-bullet {list-style: none}
	-->
	</style>


	</head>

	<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
	<a name="Writing-a-Frame-Filter"></a>
	<div class="header">
	<p>
	Next: <a href="Unwinding-Frames-in-Python.html#Unwinding-Frames-in-Python" accesskey="n" rel="next">Unwinding Frames in Python</a>, Previous: <a href="Frame-Decorator-API.html#Frame-Decorator-API" accesskey="p" rel="prev">Frame Decorator API</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a>   [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
	</div>
	<hr>
	<a name="Writing-a-Frame-Filter-1"></a>
	<h4 class="subsubsection">23.2.2.11 Writing a Frame Filter</h4>
	<a name="index-writing-a-frame-filter"></a>

	<p>There are three basic elements that a frame filter must implement: it
	must correctly implement the documented interface (see <a href="Frame-Filter-API.html#Frame-Filter-API">Frame Filter API</a>), it must register itself with <small>GDB</small>, and finally, it must
	decide if it is to work on the data provided by <small>GDB</small>. In all
	cases, whether it works on the iterator or not, each frame filter must
	return an iterator. A bare-bones frame filter follows the pattern in
	the following example.
	</p>
	<div class="smallexample">
	<pre class="smallexample">import gdb

	class FrameFilter():

	def __init__(self):
	# Frame filter attribute creation.
	#
	# 'name' is the name of the filter that GDB will display.
	#
	# 'priority' is the priority of the filter relative to other
	# filters.
	#
	# 'enabled' is a boolean that indicates whether this filter is
	# enabled and should be executed.

	self.name = "Foo"
	self.priority = 100
	self.enabled = True

	# Register this frame filter with the global frame_filters
	# dictionary.
	gdb.frame_filters[self.name] = self

	def filter(self, frame_iter):
	# Just return the iterator.
	return frame_iter
	</pre></div>

	<p>The frame filter in the example above implements the three
	requirements for all frame filters. It implements the API, self
	registers, and makes a decision on the iterator (in this case, it just
	returns the iterator untouched).
	</p>
	<p>The first step is attribute creation and assignment, and as shown in
	the comments the filter assigns the following attributes: <code>name</code>,
	<code>priority</code> and whether the filter should be enabled with the
	<code>enabled</code> attribute.
	</p>
	<p>The second step is registering the frame filter with the dictionary or
	dictionaries that the frame filter has interest in. As shown in the
	comments, this filter just registers itself with the global dictionary
	<code>gdb.frame_filters</code>. As noted earlier, <code>gdb.frame_filters</code>
	is a dictionary that is initialized in the <code>gdb</code> module when
	<small>GDB</small> starts. What dictionary a filter registers with is an
	important consideration. Generally, if a filter is specific to a set
	of code, it should be registered either in the <code>objfile</code> or
	<code>progspace</code> dictionaries as they are specific to the program
	currently loaded in <small>GDB</small>. The global dictionary is always
	present in <small>GDB</small> and is never unloaded. Any filters registered
	with the global dictionary will exist until <small>GDB</small> exits. To
	avoid filters that may conflict, it is generally better to register
	frame filters against the dictionaries that more closely align with
	the usage of the filter currently in question. See <a href="Python-Auto_002dloading.html#Python-Auto_002dloading">Python Auto-loading</a>, for further information on auto-loading Python scripts.
	</p>
	<p><small>GDB</small> takes a hands-off approach to frame filter registration,
	therefore it is the frame filter’s responsibility to ensure
	registration has occurred, and that any exceptions are handled
	appropriately. In particular, you may wish to handle exceptions
	relating to Python dictionary key uniqueness. It is mandatory that
	the dictionary key is the same as frame filter’s <code>name</code>
	attribute. When a user manages frame filters (see <a href="Frame-Filter-Management.html#Frame-Filter-Management">Frame Filter Management</a>), the names <small>GDB</small> will display are those contained
	in the <code>name</code> attribute.
	</p>
	<p>The final step of this example is the implementation of the
	<code>filter</code> method. As shown in the example comments, we define the
	<code>filter</code> method and note that the method must take an iterator,
	and also must return an iterator. In this bare-bones example, the
	frame filter is not very useful as it just returns the iterator
	untouched. However this is a valid operation for frame filters that
	have the <code>enabled</code> attribute set, but decide not to operate on
	any frames.
	</p>
	<p>In the next example, the frame filter operates on all frames and
	utilizes a frame decorator to perform some work on the frames.
	See <a href="Frame-Decorator-API.html#Frame-Decorator-API">Frame Decorator API</a>, for further information on the frame
	decorator interface.
	</p>
	<p>This example works on inlined frames. It highlights frames which are
	inlined by tagging them with an “[inlined]” tag. By applying a
	frame decorator to all frames with the Python <code>itertools imap</code>
	method, the example defers actions to the frame decorator. Frame
	decorators are only processed when <small>GDB</small> prints the backtrace.
	</p>
	<p>This introduces a new decision making topic: whether to perform
	decision making operations at the filtering step, or at the printing
	step. In this example’s approach, it does not perform any filtering
	decisions at the filtering step beyond mapping a frame decorator to
	each frame. This allows the actual decision making to be performed
	when each frame is printed. This is an important consideration, and
	well worth reflecting upon when designing a frame filter. An issue
	that frame filters should avoid is unwinding the stack if possible.
	Some stacks can run very deep, into the tens of thousands in some
	cases. To search every frame to determine if it is inlined ahead of
	time may be too expensive at the filtering step. The frame filter
	cannot know how many frames it has to iterate over, and it would have
	to iterate through them all. This ends up duplicating effort as
	<small>GDB</small> performs this iteration when it prints the frames.
	</p>
	<p>In this example decision making can be deferred to the printing step.
	As each frame is printed, the frame decorator can examine each frame
	in turn when <small>GDB</small> iterates. From a performance viewpoint,
	this is the most appropriate decision to make as it avoids duplicating
	the effort that the printing step would undertake anyway. Also, if
	there are many frame filters unwinding the stack during filtering, it
	can substantially delay the printing of the backtrace which will
	result in large memory usage, and a poor user experience.
	</p>
	<div class="smallexample">
	<pre class="smallexample">class InlineFilter():

	def __init__(self):
	self.name = "InlinedFrameFilter"
	self.priority = 100
	self.enabled = True
	gdb.frame_filters[self.name] = self

	def filter(self, frame_iter):
	frame_iter = itertools.imap(InlinedFrameDecorator,
	frame_iter)
	return frame_iter
	</pre></div>

	<p>This frame filter is somewhat similar to the earlier example, except
	that the <code>filter</code> method applies a frame decorator object called
	<code>InlinedFrameDecorator</code> to each element in the iterator. The
	<code>imap</code> Python method is light-weight. It does not proactively
	iterate over the iterator, but rather creates a new iterator which
	wraps the existing one.
	</p>
	<p>Below is the frame decorator for this example.
	</p>
	<div class="smallexample">
	<pre class="smallexample">class InlinedFrameDecorator(FrameDecorator):

	def __init__(self, fobj):
	super(InlinedFrameDecorator, self).__init__(fobj)

	def function(self):
	frame = fobj.inferior_frame()
	name = str(frame.name())

	if frame.type() == gdb.INLINE_FRAME:
	name = name + " [inlined]"

	return name
	</pre></div>

	<p>This frame decorator only defines and overrides the <code>function</code>
	method. It lets the supplied <code>FrameDecorator</code>, which is shipped
	with <small>GDB</small>, perform the other work associated with printing
	this frame.
	</p>
	<p>The combination of these two objects create this output from a
	backtrace:
	</p>
	<div class="smallexample">
	<pre class="smallexample">#0 0x004004e0 in bar () at inline.c:11
	#1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
	#2 0x00400566 in main () at inline.c:31
	</pre></div>

	<p>So in the case of this example, a frame decorator is applied to all
	frames, regardless of whether they may be inlined or not. As
	<small>GDB</small> iterates over the iterator produced by the frame filters,
	<small>GDB</small> executes each frame decorator which then makes a decision
	on what to print in the <code>function</code> callback. Using a strategy
	like this is a way to defer decisions on the frame content to printing
	time.
	</p>
	<a name="Eliding-Frames"></a>
	<h4 class="subheading">Eliding Frames</h4>

	<p>It might be that the above example is not desirable for representing
	inlined frames, and a hierarchical approach may be preferred. If we
	want to hierarchically represent frames, the <code>elided</code> frame
	decorator interface might be preferable.
	</p>
	<p>This example approaches the issue with the <code>elided</code> method. This
	example is quite long, but very simplistic. It is out-of-scope for
	this section to write a complete example that comprehensively covers
	all approaches of finding and printing inlined frames. However, this
	example illustrates the approach an author might use.
	</p>
	<p>This example comprises of three sections.
	</p>
	<div class="smallexample">
	<pre class="smallexample">class InlineFrameFilter():

	def __init__(self):
	self.name = "InlinedFrameFilter"
	self.priority = 100
	self.enabled = True
	gdb.frame_filters[self.name] = self

	def filter(self, frame_iter):
	return ElidingInlineIterator(frame_iter)
	</pre></div>

	<p>This frame filter is very similar to the other examples. The only
	difference is this frame filter is wrapping the iterator provided to
	it (<code>frame_iter</code>) with a custom iterator called
	<code>ElidingInlineIterator</code>. This again defers actions to when
	<small>GDB</small> prints the backtrace, as the iterator is not traversed
	until printing.
	</p>
	<p>The iterator for this example is as follows. It is in this section of
	the example where decisions are made on the content of the backtrace.
	</p>
	<div class="smallexample">
	<pre class="smallexample">class ElidingInlineIterator:
	def __init__(self, ii):
	self.input_iterator = ii

	def __iter__(self):
	return self

	def next(self):
	frame = next(self.input_iterator)

	if frame.inferior_frame().type() != gdb.INLINE_FRAME:
	return frame

	try:
	eliding_frame = next(self.input_iterator)
	except StopIteration:
	return frame
	return ElidingFrameDecorator(eliding_frame, [frame])
	</pre></div>

	<p>This iterator implements the Python iterator protocol. When the
	<code>next</code> function is called (when <small>GDB</small> prints each frame),
	the iterator checks if this frame decorator, <code>frame</code>, is wrapping
	an inlined frame. If it is not, it returns the existing frame decorator
	untouched. If it is wrapping an inlined frame, it assumes that the
	inlined frame was contained within the next oldest frame,
	<code>eliding_frame</code>, which it fetches. It then creates and returns a
	frame decorator, <code>ElidingFrameDecorator</code>, which contains both the
	elided frame, and the eliding frame.
	</p>
	<div class="smallexample">
	<pre class="smallexample">class ElidingInlineDecorator(FrameDecorator):

	def __init__(self, frame, elided_frames):
	super(ElidingInlineDecorator, self).__init__(frame)
	self.frame = frame
	self.elided_frames = elided_frames

	def elided(self):
	return iter(self.elided_frames)
	</pre></div>

	<p>This frame decorator overrides one function and returns the inlined
	frame in the <code>elided</code> method. As before it lets
	<code>FrameDecorator</code> do the rest of the work involved in printing
	this frame. This produces the following output.
	</p>
	<div class="smallexample">
	<pre class="smallexample">#0 0x004004e0 in bar () at inline.c:11
	#2 0x00400529 in main () at inline.c:25
	#1 0x00400529 in max (b=6, a=12) at inline.c:15
	</pre></div>

	<p>In that output, <code>max</code> which has been inlined into <code>main</code> is
	printed hierarchically. Another approach would be to combine the
	<code>function</code> method, and the <code>elided</code> method to both print a
	marker in the inlined frame, and also show the hierarchical
	relationship.
	</p>
	<hr>
	<div class="header">
	<p>
	Next: <a href="Unwinding-Frames-in-Python.html#Unwinding-Frames-in-Python" accesskey="n" rel="next">Unwinding Frames in Python</a>, Previous: <a href="Frame-Decorator-API.html#Frame-Decorator-API" accesskey="p" rel="prev">Frame Decorator API</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a>   [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
	</div>



	</body>
	</html>