[Lldb-commits] [lldb] r138236 - in /lldb/trunk: examples/synthetic/StdVectorSynthProvider.py examples/synthetic/gnu_libstdcpp.py www/varformats.html
Enrico Granata
granata.enrico at gmail.com
Mon Aug 22 09:10:25 PDT 2011
Author: enrico
Date: Mon Aug 22 11:10:25 2011
New Revision: 138236
URL: http://llvm.org/viewvc/llvm-project?rev=138236&view=rev
Log:
Exception-awareness for gnu_libstdcpp formatters ; Documentation update
Modified:
lldb/trunk/examples/synthetic/StdVectorSynthProvider.py
lldb/trunk/examples/synthetic/gnu_libstdcpp.py
lldb/trunk/www/varformats.html
Modified: lldb/trunk/examples/synthetic/StdVectorSynthProvider.py
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/examples/synthetic/StdVectorSynthProvider.py?rev=138236&r1=138235&r2=138236&view=diff
==============================================================================
--- lldb/trunk/examples/synthetic/StdVectorSynthProvider.py (original)
+++ lldb/trunk/examples/synthetic/StdVectorSynthProvider.py Mon Aug 22 11:10:25 2011
@@ -25,12 +25,7 @@
if finish_val > end_val:
return 0
- # We might still get things wrong, so cap things at 256 items for now
- # TODO: read a target "settings set" variable for this to allow it to
- # be customized
num_children = (finish_val-start_val)/self.data_size
- if num_children > 256:
- return 256
return num_children
def get_child_index(self,name):
Modified: lldb/trunk/examples/synthetic/gnu_libstdcpp.py
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/examples/synthetic/gnu_libstdcpp.py?rev=138236&r1=138235&r2=138236&view=diff
==============================================================================
--- lldb/trunk/examples/synthetic/gnu_libstdcpp.py (original)
+++ lldb/trunk/examples/synthetic/gnu_libstdcpp.py Mon Aug 22 11:10:25 2011
@@ -1,11 +1,10 @@
import re
# C++ STL formatters for LLDB
-# These formatters are based upon the version of the STL that ships
-# with Mac OS X Snow Leopard 10.6.8 and OS X Lion 10.7.0
-# The STL implementation *might* change on other releases of Apple's
-# operating system and library infrastructure, and might be different on
-# other operating systems
+# These formatters are based upon the version of the GNU libstdc++
+# as it ships with Mac OS X 10.6.8 and 10.7.0
+# You are encouraged to look at the STL implementation for your platform
+# before relying on these formatters to do the right thing for your setup
class StdListSynthProvider:
@@ -14,34 +13,45 @@
self.update()
def num_children(self):
- next_val = self.next.GetValueAsUnsigned(0)
- prev_val = self.prev.GetValueAsUnsigned(0)
- # After a std::list has been initialized, both next and prev will be non-NULL
- if next_val == 0 or prev_val == 0:
- return 0
- if next_val == self.node_address:
- return 0
- if next_val == prev_val:
- return 1
- size = 2
- current = self.next
- while current.GetChildMemberWithName('_M_next').GetValueAsUnsigned(0) != self.node_address:
- size = size + 1
- current = current.GetChildMemberWithName('_M_next')
- return (size - 1)
+ try:
+ next_val = self.next.GetValueAsUnsigned(0)
+ prev_val = self.prev.GetValueAsUnsigned(0)
+ # After a std::list has been initialized, both next and prev will be non-NULL
+ if next_val == 0 or prev_val == 0:
+ return 0
+ if next_val == self.node_address:
+ return 0
+ if next_val == prev_val:
+ return 1
+ size = 2
+ current = self.next
+ while current.GetChildMemberWithName('_M_next').GetValueAsUnsigned(0) != self.node_address:
+ size = size + 1
+ current = current.GetChildMemberWithName('_M_next')
+ return (size - 1)
+ except:
+ return 0;
def get_child_index(self,name):
- return int(name.lstrip('[').rstrip(']'))
+ try:
+ return int(name.lstrip('[').rstrip(']'))
+ except:
+ return -1
def get_child_at_index(self,index):
+ if index < 0:
+ return None;
if index >= self.num_children():
return None;
- offset = index
- current = self.next
- while offset > 0:
- current = current.GetChildMemberWithName('_M_next')
- offset = offset - 1
- return current.CreateChildAtOffset('['+str(index)+']',2*current.GetType().GetByteSize(),self.data_type)
+ try:
+ offset = index
+ current = self.next
+ while offset > 0:
+ current = current.GetChildMemberWithName('_M_next')
+ offset = offset - 1
+ return current.CreateChildAtOffset('['+str(index)+']',2*current.GetType().GetByteSize(),self.data_type)
+ except:
+ return None:
def extract_type_name(self,name):
self.type_name = name[16:]
@@ -59,17 +69,20 @@
self.type_name_nospaces = self.type_name.replace(", ", ",")
def update(self):
- impl = self.valobj.GetChildMemberWithName('_M_impl')
- node = impl.GetChildMemberWithName('_M_node')
- self.extract_type_name(impl.GetType().GetName())
- self.node_address = self.valobj.AddressOf().GetValueAsUnsigned(0)
- self.next = node.GetChildMemberWithName('_M_next')
- self.prev = node.GetChildMemberWithName('_M_prev')
- self.data_type = node.GetTarget().FindFirstType(self.type_name)
- # tries to fight against a difference in formatting type names between gcc and clang
- if self.data_type.IsValid() == False:
- self.data_type = node.GetTarget().FindFirstType(self.type_name_nospaces)
- self.data_size = self.data_type.GetByteSize()
+ try:
+ impl = self.valobj.GetChildMemberWithName('_M_impl')
+ node = impl.GetChildMemberWithName('_M_node')
+ self.extract_type_name(impl.GetType().GetName())
+ self.node_address = self.valobj.AddressOf().GetValueAsUnsigned(0)
+ self.next = node.GetChildMemberWithName('_M_next')
+ self.prev = node.GetChildMemberWithName('_M_prev')
+ self.data_type = node.GetTarget().FindFirstType(self.type_name)
+ # tries to fight against a difference in formatting type names between gcc and clang
+ if self.data_type.IsValid() == False:
+ self.data_type = node.GetTarget().FindFirstType(self.type_name_nospaces)
+ self.data_size = self.data_type.GetByteSize()
+ except:
+ pass
class StdVectorSynthProvider:
@@ -78,45 +91,59 @@
self.update()
def num_children(self):
- start_val = self.start.GetValueAsUnsigned(0)
- finish_val = self.finish.GetValueAsUnsigned(0)
- end_val = self.end.GetValueAsUnsigned(0)
- # Before a vector has been constructed, it will contain bad values
- # so we really need to be careful about the length we return since
- # unitialized data can cause us to return a huge number. We need
- # to also check for any of the start, finish or end of storage values
- # being zero (NULL). If any are, then this vector has not been
- # initialized yet and we should return zero
-
- # Make sure nothing is NULL
- if start_val == 0 or finish_val == 0 or end_val == 0:
- return 0
- # Make sure start is less than finish
- if start_val >= finish_val:
- return 0
- # Make sure finish is less than or equal to end of storage
- if finish_val > end_val:
- return 0
-
- num_children = (finish_val-start_val)/self.data_size
- return num_children
+ try:
+ start_val = self.start.GetValueAsUnsigned(0)
+ finish_val = self.finish.GetValueAsUnsigned(0)
+ end_val = self.end.GetValueAsUnsigned(0)
+ # Before a vector has been constructed, it will contain bad values
+ # so we really need to be careful about the length we return since
+ # unitialized data can cause us to return a huge number. We need
+ # to also check for any of the start, finish or end of storage values
+ # being zero (NULL). If any are, then this vector has not been
+ # initialized yet and we should return zero
+
+ # Make sure nothing is NULL
+ if start_val == 0 or finish_val == 0 or end_val == 0:
+ return 0
+ # Make sure start is less than finish
+ if start_val >= finish_val:
+ return 0
+ # Make sure finish is less than or equal to end of storage
+ if finish_val > end_val:
+ return 0
+
+ num_children = (finish_val-start_val)/self.data_size
+ return num_children
+ except:
+ return 0;
def get_child_index(self,name):
- return int(name.lstrip('[').rstrip(']'))
+ try:
+ return int(name.lstrip('[').rstrip(']'))
+ except:
+ return -1
def get_child_at_index(self,index):
+ if index < 0:
+ return None;
if index >= self.num_children():
return None;
- offset = index * self.data_size
- return self.start.CreateChildAtOffset('['+str(index)+']',offset,self.data_type)
+ try:
+ offset = index * self.data_size
+ return self.start.CreateChildAtOffset('['+str(index)+']',offset,self.data_type)
+ except:
+ return None
def update(self):
- impl = self.valobj.GetChildMemberWithName('_M_impl')
- self.start = impl.GetChildMemberWithName('_M_start')
- self.finish = impl.GetChildMemberWithName('_M_finish')
- self.end = impl.GetChildMemberWithName('_M_end_of_storage')
- self.data_type = self.start.GetType().GetPointeeType()
- self.data_size = self.data_type.GetByteSize()
+ try:
+ impl = self.valobj.GetChildMemberWithName('_M_impl')
+ self.start = impl.GetChildMemberWithName('_M_start')
+ self.finish = impl.GetChildMemberWithName('_M_finish')
+ self.end = impl.GetChildMemberWithName('_M_end_of_storage')
+ self.data_type = self.start.GetType().GetPointeeType()
+ self.data_size = self.data_type.GetByteSize()
+ except:
+ pass
class StdMapSynthProvider:
@@ -126,21 +153,24 @@
self.update()
def update(self):
- self.Mt = self.valobj.GetChildMemberWithName('_M_t')
- self.Mimpl = self.Mt.GetChildMemberWithName('_M_impl')
- self.Mheader = self.Mimpl.GetChildMemberWithName('_M_header')
- # from libstdc++ implementation of _M_root for rbtree
- self.Mroot = self.Mheader.GetChildMemberWithName('_M_parent')
- # the stuff into the tree is actually a std::pair<const key, value>
- # life would be much easier if gcc had a coherent way to print out
- # template names in debug info
- self.expand_clang_type_name()
- self.expand_gcc_type_name()
- self.data_type = self.Mt.GetTarget().FindFirstType(self.clang_type_name)
- if self.data_type.IsValid() == False:
- self.data_type = self.Mt.GetTarget().FindFirstType(self.gcc_type_name)
- self.data_size = self.data_type.GetByteSize()
- self.skip_size = self.Mheader.GetType().GetByteSize()
+ try:
+ self.Mt = self.valobj.GetChildMemberWithName('_M_t')
+ self.Mimpl = self.Mt.GetChildMemberWithName('_M_impl')
+ self.Mheader = self.Mimpl.GetChildMemberWithName('_M_header')
+ # from libstdc++ implementation of _M_root for rbtree
+ self.Mroot = self.Mheader.GetChildMemberWithName('_M_parent')
+ # the stuff into the tree is actually a std::pair<const key, value>
+ # life would be much easier if gcc had a coherent way to print out
+ # template names in debug info
+ self.expand_clang_type_name()
+ self.expand_gcc_type_name()
+ self.data_type = self.Mt.GetTarget().FindFirstType(self.clang_type_name)
+ if self.data_type.IsValid() == False:
+ self.data_type = self.Mt.GetTarget().FindFirstType(self.gcc_type_name)
+ self.data_size = self.data_type.GetByteSize()
+ self.skip_size = self.Mheader.GetType().GetByteSize()
+ except:
+ pass
def expand_clang_type_name(self):
type_name = self.Mimpl.GetType().GetName()
@@ -180,24 +210,35 @@
self.gcc_type_name = type_name
def num_children(self):
- root_ptr_val = self.node_ptr_value(self.Mroot)
- if root_ptr_val == 0:
+ try:
+ root_ptr_val = self.node_ptr_value(self.Mroot)
+ if root_ptr_val == 0:
+ return 0;
+ return self.Mimpl.GetChildMemberWithName('_M_node_count').GetValueAsUnsigned(0)
+ except:
return 0;
- return self.Mimpl.GetChildMemberWithName('_M_node_count').GetValueAsUnsigned(0)
def get_child_index(self,name):
- return int(name.lstrip('[').rstrip(']'))
+ try:
+ return int(name.lstrip('[').rstrip(']'))
+ except:
+ return -1
def get_child_at_index(self,index):
+ if index < 0:
+ return None
if index >= self.num_children():
return None;
- offset = index
- current = self.left(self.Mheader);
- while offset > 0:
- current = self.increment_node(current)
- offset = offset - 1;
- # skip all the base stuff and get at the data
- return current.CreateChildAtOffset('['+str(index)+']',self.skip_size,self.data_type)
+ try:
+ offset = index
+ current = self.left(self.Mheader);
+ while offset > 0:
+ current = self.increment_node(current)
+ offset = offset - 1;
+ # skip all the base stuff and get at the data
+ return current.CreateChildAtOffset('['+str(index)+']',self.skip_size,self.data_type)
+ except:
+ return None
# utility functions
def node_ptr_value(self,node):
Modified: lldb/trunk/www/varformats.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/varformats.html?rev=138236&r1=138235&r2=138236&view=diff
==============================================================================
--- lldb/trunk/www/varformats.html (original)
+++ lldb/trunk/www/varformats.html Mon Aug 22 11:10:25 2011
@@ -51,20 +51,21 @@
-> -2, z="3")<br>
</code> </p>
- <p>There are two kinds of printing options: <span
- style="font-style: italic;">summary</span> and <span
- style="font-style: italic;">format</span>. While a
- detailed description of both will be given below, one
- can briefly say that a summary is mainly used for
- aggregate types, while a format is attached to primitive
- types.</p>
+ <p>There are several features related to data visualization: <span
+ style="font-style: italic;">formats</span>, <span
+ style="font-style: italic;">summaries</span>, <span
+ style="font-style: italic;">filters</span>, <span
+ style="font-style: italic;">synthetic children</span>.</p>
- <p>To reflect this, the the <b>type</b> command has two
+ <p>To reflect this, the the <b>type</b> command has four
subcommands:<br>
</p>
<p><code>type format</code></p>
<p><code>type summary</code></p>
+ <p><code>type filter</code></p>
+ <p><code>type synthetic</code></p>
+
<p>These commands are meant to bind printing options to
types. When variables are printed, LLDB will first check
@@ -73,8 +74,7 @@
the default choices.<br>
</p>
- <p>The two commands <code>type format</code> and <code>type
- summary</code> each have four subcommands:<br>
+ <p>Each of the commands has four subcommands available:<br>
</p>
<p><code>add</code>: associates a new printing option to one
or more types</p>
@@ -524,6 +524,14 @@
<td><b>%L</b></td>
<td>Use this object's location (memory address, register name, ...)</td>
</tr>
+ <tr valign="top">
+ <td><b>%#</b></td>
+ <td>Use the count of the children of this object</td>
+ </tr>
+ <tr valign="top">
+ <td><b>%T</b></td>
+ <td>Use this object's datatype name</td>
+ </tr>
</tbody>
</table>
@@ -939,19 +947,77 @@
</div>
</div>
+ <div class="post">
+ <h1 class="postheader">Synthetic children</h1>
+ <div class="postcontent">
+ <p>Summaries work well when one is able to navigate through an expression path.
+ In order for LLDB to do so, appropriate debugging information must be available.</p>
+ <p>Some types are <i>opaque</i>, i.e. no knowledge of their internals is provided.
+ When that's the case, expression paths do not work correctly.</p>
+ <p>In other cases, the internals are available to use in expression paths, but they
+ do not provide a user-friendly representation of the object's value.</p>
+ <p>For instance, consider an STL vector:</p>
+ <code>
+ <b>(lldb)</b> frame variable numbers -T<br/>
+ (std::vector<int>) numbers = {<br/>
+ (std::_Vector_base<int, std::allocator<int> >) std::_Vector_base<int, std::allocator<int> > = {<br/>
+ (std::_Vector_base<int, std::allocator<int> >::_Vector_impl) _M_impl = {<br/>
+ (int *) _M_start = 0x00000001001008a0<br/>
+ (int *) _M_finish = 0x00000001001008a8<br/>
+ (int *) _M_end_of_storage = 0x00000001001008a8<br/>
+ }<br/>
+ }<br/>
+ }<br/>
+ </code>
+ <p>Here, you can see how the type is implemented, and you can write a summary for that implementation
+ but that is not going to help you infer what items are actually stored in the vector.</p>
+ <p>What you would like to see is probably something like:</p>
+ <code>
+ <b>(lldb)</b> frame variable numbers -T<br/>
+ (std::vector<int>) numbers = {<br/>
+ (int) [0] = 1<br/>
+ (int) [1] = 12<br/>
+ (int) [2] = 123<br/>
+ (int) [3] = 1234<br/>
+ }<br/>
+ </code>
+ <p>Synthetic children are a way to get that result.</p>
+ <p>The feature is based upon the idea of providing a new set of children for a variable that replaces the ones
+ available by default through the debug information. In the example, we can use synthetic children to provide
+ the vector items as children for the std::vector object.</p>
+ <p>In order to create synthetic children, you need to provide a Python class that adheres to a given <i>interface</i>
+ (the word is italicized because Python has no explicit notion of interface. By that word we mean a given set of methods
+ must be implemented by the Python class):</p>
+ <code>
+ <font color=blue>class</font> SyntheticChildrenProvider:<br/>
+ <font color=blue>def</font> __init__(self, valobj, dict):<br/>
+ this call should initialize the Python object using valobj as the variable to provide synthetic children for <br/>
+ <font color=blue>def</font> num_children(self): <br/>
+ this call should return the number of children that you want your object to have <br/>
+ <font color=blue>def</font> get_child_index(self,name): <br/>
+ this call should return the index of the synthetic child whose name is given as argument <br/>
+ <font color=blue>def</font> get_child_at_index(self,index): <br/>
+ this call should return a new LLDB SBValue object representing the child at the index given as argument <br/>
+ <font color=blue>def</font> update(self): <br/>
+ this call should be used to update the internal state of this Python object whenever the state of the variables in LLDB changes.
+ Currently this method is optional, because the internal state of synthetic children providers will not be preserved. However, this is meant to change in future versions
+ of LLDB.<br/>
+ </code>
+ <p>For examples of how synthetic children are created, you are encouraged to look at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/">examples/synthetic</a> in the LLDB trunk.</p>
+ </div>
+ </div>
<div class="post">
- <h1 class="postheader">Finding summaries 101</h1>
+ <h1 class="postheader">Finding formatters 101</h1>
<div class="postcontent">
<p>While the rules for finding an appropriate format for a
type are relatively simple (just go through typedef
- hierarchies), summaries follow a more complicated
- process in finding the right summary string for a
- variable. Namely, what happens is:</p>
+ hierarchies), searching formatters for a type goes through
+ a rather intricate set of rules. Namely, what happens is:</p>
<ul>
- <li>If there is a summary for the type of the variable,
+ <li>If there is a formatter for the type of the variable,
use it</li>
- <li>If this object is a pointer, and there is a summary
+ <li>If this object is a pointer, and there is a formatter
for the pointee type that does not skip pointers, use
it</li>
<li>If this object is a reference, and there is a
@@ -959,7 +1025,11 @@
references, use it</li>
<li>If this object is an Objective-C class with a parent
class, look at the parent class (and parent of parent,
- ...)</li>
+ ...). This phase can be based upon the actual type of
+ the object as inferred by the value of its <code>isa</code>
+ pointer, or upon the debugging information inferred by the
+ debugger. The user can use the dynamic typing settings to
+ elect one or the other behavior.</li>
<li>If this object is a C++ class with base classes,
look at base classes (and bases of bases, ...)</li>
<li>If this object is a C++ class with virtual base
@@ -986,6 +1056,7 @@
<li>There's no way to do multiple dereferencing, and you
need to be careful what the dereferencing operation is
binding to in complicated scenarios</li>
+ <li>Synthetic children providers cannot have a permanent state</li>
<li><code>type format add</code> does not support the <code>-x</code>
option</li>
<strike><li>Object location cannot be printed in the summary
More information about the lldb-commits
mailing list