1<html lang="en"> 2<head> 3<title>Frame Filter API - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Python-API.html#Python-API" title="Python API"> 9<link rel="prev" href="Type-Printing-API.html#Type-Printing-API" title="Type Printing API"> 10<link rel="next" href="Frame-Decorator-API.html#Frame-Decorator-API" title="Frame Decorator API"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988-2013 Free Software Foundation, Inc. 14 15Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.3 or 17any later version published by the Free Software Foundation; with the 18Invariant Sections being ``Free Software'' and ``Free Software Needs 19Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 20and with the Back-Cover Texts as in (a) below. 21 22(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 23this GNU Manual. Buying copies from GNU Press supports the FSF in 24developing GNU and promoting software freedom.'' 25--> 26<meta http-equiv="Content-Style-Type" content="text/css"> 27<style type="text/css"><!-- 28 pre.display { font-family:inherit } 29 pre.format { font-family:inherit } 30 pre.smalldisplay { font-family:inherit; font-size:smaller } 31 pre.smallformat { font-family:inherit; font-size:smaller } 32 pre.smallexample { font-size:smaller } 33 pre.smalllisp { font-size:smaller } 34 span.sc { font-variant:small-caps } 35 span.roman { font-family:serif; font-weight:normal; } 36 span.sansserif { font-family:sans-serif; font-weight:normal; } 37--></style> 38<link rel="stylesheet" type="text/css" href="../cs.css"> 39</head> 40<body> 41<div class="node"> 42<a name="Frame-Filter-API"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Frame-Decorator-API.html#Frame-Decorator-API">Frame Decorator API</a>, 45Previous: <a rel="previous" accesskey="p" href="Type-Printing-API.html#Type-Printing-API">Type Printing API</a>, 46Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a> 47<hr> 48</div> 49 50<h5 class="subsubsection">23.2.2.9 Filtering Frames.</h5> 51 52<p><a name="index-frame-filters-api-1883"></a> 53Frame filters are Python objects that manipulate the visibility of a 54frame or frames when a backtrace (see <a href="Backtrace.html#Backtrace">Backtrace</a>) is printed by 55<span class="sc">gdb</span>. 56 57 <p>Only commands that print a backtrace, or, in the case of <span class="sc">gdb/mi</span> 58commands (see <a href="GDB_002fMI.html#GDB_002fMI">GDB/MI</a>), those that return a collection of frames 59are affected. The commands that work with frame filters are: 60 61 <p><code>backtrace</code> (see <a href="backtrace_002dcommand.html#backtrace_002dcommand">The backtrace command</a>), 62<code>-stack-list-frames</code> 63(see <a href="_002dstack_002dlist_002dframes.html#g_t_002dstack_002dlist_002dframes">The -stack-list-frames command</a>), 64<code>-stack-list-variables</code> (see <a href="_002dstack_002dlist_002dvariables.html#g_t_002dstack_002dlist_002dvariables">The -stack-list-variables command</a>), <code>-stack-list-arguments</code> 65see <a href="_002dstack_002dlist_002darguments.html#g_t_002dstack_002dlist_002darguments">The -stack-list-arguments command</a>) and 66<code>-stack-list-locals</code> (see <a href="_002dstack_002dlist_002dlocals.html#g_t_002dstack_002dlist_002dlocals">The -stack-list-locals command</a>). 67 68 <p>A frame filter works by taking an iterator as an argument, applying 69actions to the contents of that iterator, and returning another 70iterator (or, possibly, the same iterator it was provided in the case 71where the filter does not perform any operations). Typically, frame 72filters utilize tools such as the Python's <code>itertools</code> module to 73work with and create new iterators from the source iterator. 74Regardless of how a filter chooses to apply actions, it must not alter 75the underlying <span class="sc">gdb</span> frame or frames, or attempt to alter the 76call-stack within <span class="sc">gdb</span>. This preserves data integrity within 77<span class="sc">gdb</span>. Frame filters are executed on a priority basis and care 78should be taken that some frame filters may have been executed before, 79and that some frame filters will be executed after. 80 81 <p>An important consideration when designing frame filters, and well 82worth reflecting upon, is that frame filters should avoid unwinding 83the call stack if possible. Some stacks can run very deep, into the 84tens of thousands in some cases. To search every frame when a frame 85filter executes may be too expensive at that step. The frame filter 86cannot know how many frames it has to iterate over, and it may have to 87iterate through them all. This ends up duplicating effort as 88<span class="sc">gdb</span> performs this iteration when it prints the frames. If 89the filter can defer unwinding frames until frame decorators are 90executed, after the last filter has executed, it should. See <a href="Frame-Decorator-API.html#Frame-Decorator-API">Frame Decorator API</a>, for more information on decorators. Also, there are 91examples for both frame decorators and filters in later chapters. 92See <a href="Writing-a-Frame-Filter.html#Writing-a-Frame-Filter">Writing a Frame Filter</a>, for more information. 93 94 <p>The Python dictionary <code>gdb.frame_filters</code> contains key/object 95pairings that comprise a frame filter. Frame filters in this 96dictionary are called <code>global</code> frame filters, and they are 97available when debugging all inferiors. These frame filters must 98register with the dictionary directly. In addition to the 99<code>global</code> dictionary, there are other dictionaries that are loaded 100with different inferiors via auto-loading (see <a href="Python-Auto_002dloading.html#Python-Auto_002dloading">Python Auto-loading</a>). The two other areas where frame filter dictionaries 101can be found are: <code>gdb.Progspace</code> which contains a 102<code>frame_filters</code> dictionary attribute, and each <code>gdb.Objfile</code> 103object which also contains a <code>frame_filters</code> dictionary 104attribute. 105 106 <p>When a command is executed from <span class="sc">gdb</span> that is compatible with 107frame filters, <span class="sc">gdb</span> combines the <code>global</code>, 108<code>gdb.Progspace</code> and all <code>gdb.Objfile</code> dictionaries currently 109loaded. All of the <code>gdb.Objfile</code> dictionaries are combined, as 110several frames, and thus several object files, might be in use. 111<span class="sc">gdb</span> then prunes any frame filter whose <code>enabled</code> 112attribute is <code>False</code>. This pruned list is then sorted according 113to the <code>priority</code> attribute in each filter. 114 115 <p>Once the dictionaries are combined, pruned and sorted, <span class="sc">gdb</span> 116creates an iterator which wraps each frame in the call stack in a 117<code>FrameDecorator</code> object, and calls each filter in order. The 118output from the previous filter will always be the input to the next 119filter, and so on. 120 121 <p>Frame filters have a mandatory interface which each frame filter must 122implement, defined here: 123 124<div class="defun"> 125— Function: <b>FrameFilter.filter</b> (<var>iterator</var>)<var><a name="index-FrameFilter_002efilter-1884"></a></var><br> 126<blockquote><p><span class="sc">gdb</span> will call this method on a frame filter when it has 127reached the order in the priority list for that filter. 128 129 <p>For example, if there are four frame filters: 130 131 <pre class="smallexample"> Name Priority 132 133 Filter1 5 134 Filter2 10 135 Filter3 100 136 Filter4 1 137</pre> 138 <p>The order that the frame filters will be called is: 139 140 <pre class="smallexample"> Filter3 -> Filter2 -> Filter1 -> Filter4 141</pre> 142 <p>Note that the output from <code>Filter3</code> is passed to the input of 143<code>Filter2</code>, and so on. 144 145 <p>This <code>filter</code> method is passed a Python iterator. This iterator 146contains a sequence of frame decorators that wrap each 147<code>gdb.Frame</code>, or a frame decorator that wraps another frame 148decorator. The first filter that is executed in the sequence of frame 149filters will receive an iterator entirely comprised of default 150<code>FrameDecorator</code> objects. However, after each frame filter is 151executed, the previous frame filter may have wrapped some or all of 152the frame decorators with their own frame decorator. As frame 153decorators must also conform to a mandatory interface, these 154decorators can be assumed to act in a uniform manner (see <a href="Frame-Decorator-API.html#Frame-Decorator-API">Frame Decorator API</a>). 155 156 <p>This method must return an object conforming to the Python iterator 157protocol. Each item in the iterator must be an object conforming to 158the frame decorator interface. If a frame filter does not wish to 159perform any operations on this iterator, it should return that 160iterator untouched. 161 162 <p>This method is not optional. If it does not exist, <span class="sc">gdb</span> will 163raise and print an error. 164</p></blockquote></div> 165 166<div class="defun"> 167— Variable: <b>FrameFilter.name</b><var><a name="index-FrameFilter_002ename-1885"></a></var><br> 168<blockquote><p>The <code>name</code> attribute must be Python string which contains the 169name of the filter displayed by <span class="sc">gdb</span> (see <a href="Frame-Filter-Management.html#Frame-Filter-Management">Frame Filter Management</a>). This attribute may contain any combination of letters 170or numbers. Care should be taken to ensure that it is unique. This 171attribute is mandatory. 172</p></blockquote></div> 173 174<div class="defun"> 175— Variable: <b>FrameFilter.enabled</b><var><a name="index-FrameFilter_002eenabled-1886"></a></var><br> 176<blockquote><p>The <code>enabled</code> attribute must be Python boolean. This attribute 177indicates to <span class="sc">gdb</span> whether the frame filter is enabled, and 178should be considered when frame filters are executed. If 179<code>enabled</code> is <code>True</code>, then the frame filter will be executed 180when any of the backtrace commands detailed earlier in this chapter 181are executed. If <code>enabled</code> is <code>False</code>, then the frame 182filter will not be executed. This attribute is mandatory. 183</p></blockquote></div> 184 185<div class="defun"> 186— Variable: <b>FrameFilter.priority</b><var><a name="index-FrameFilter_002epriority-1887"></a></var><br> 187<blockquote><p>The <code>priority</code> attribute must be Python integer. This attribute 188controls the order of execution in relation to other frame filters. 189There are no imposed limits on the range of <code>priority</code> other than 190it must be a valid integer. The higher the <code>priority</code> attribute, 191the sooner the frame filter will be executed in relation to other 192frame filters. Although <code>priority</code> can be negative, it is 193recommended practice to assume zero is the lowest priority that a 194frame filter can be assigned. Frame filters that have the same 195priority are executed in unsorted order in that priority slot. This 196attribute is mandatory. 197</p></blockquote></div> 198 199 </body></html> 200 201