[Lldb-commits] [lldb] r138421 - in /lldb/trunk: examples/synthetic/StdVectorSynthProvider.py www/varformats.html
Enrico Granata
granata.enrico at gmail.com
Tue Aug 23 18:32:46 PDT 2011
Author: enrico
Date: Tue Aug 23 20:32:46 2011
New Revision: 138421
URL: http://llvm.org/viewvc/llvm-project?rev=138421&view=rev
Log:
More documentation changes (WIP)
Modified:
lldb/trunk/examples/synthetic/StdVectorSynthProvider.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=138421&r1=138420&r2=138421&view=diff
==============================================================================
--- lldb/trunk/examples/synthetic/StdVectorSynthProvider.py (original)
+++ lldb/trunk/examples/synthetic/StdVectorSynthProvider.py Tue Aug 23 20:32:46 2011
@@ -2,19 +2,20 @@
def __init__(self, valobj, dict):
self.valobj = valobj;
- self.update()
+ self.update() # initialize this provider
def num_children(self):
- start_val = self.start.GetValueAsUnsigned(0)
- finish_val = self.finish.GetValueAsUnsigned(0)
- end_val = self.end.GetValueAsUnsigned(0)
+ start_val = self.start.GetValueAsUnsigned(0) # read _M_start
+ finish_val = self.finish.GetValueAsUnsigned(0) # read _M_finish
+ end_val = self.end.GetValueAsUnsigned(0) # read _M_end_of_storage
+
# 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
@@ -25,23 +26,46 @@
if finish_val > end_val:
return 0
+ # pointer arithmetic: (_M_finish - _M_start) would return the number of
+ # items of type T contained in the vector. because Python has no way to know
+ # that we want to subtract two pointers instead of two integers, we have to divide
+ # by sizeof(T) to be equivalent to the C++ pointer expression
num_children = (finish_val-start_val)/self.data_size
return num_children
+ # we assume we are getting children named [0] thru [N-1]
+ # if for some reason our child name is not in this format,
+ # do not bother to show it, and return an invalid value
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):
+ # LLDB itself should never query for children < 0, but this might come
+ # from someone asking for a nonexisting child and getting -1 as 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)
-
+ # *(_M_start + index), or equivalently _M_start[index] is C++ code to
+ # read the index-th item of the vector. in Python we must make an offset
+ # that is index * sizeof(T), and then grab the value at that offset from
+ # _M_start
+ offset = index * self.data_size # index * sizeof(T)
+ return self.start.CreateChildAtOffset('['+str(index)+']',offset,self.data_type) # *(_M_start + index)
+
+ # an std::vector contains an object named _M_impl, which in turn contains
+ # three pointers, _M_start, _M_end and _M_end_of_storage. _M_start points to the
+ # beginning of the data area, _M_finish points to where the current vector elements
+ # finish, and _M_end_of_storage is the end of the currently alloc'ed memory portion
+ # (to allow resizing, a vector may allocate more memory than required)
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()
+ self.data_type = self.start.GetType().GetPointeeType() # _M_start is defined as a T*
+ self.data_size = self.data_type.GetByteSize() # sizeof(T)
Modified: lldb/trunk/www/varformats.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/varformats.html?rev=138421&r1=138420&r2=138421&view=diff
==============================================================================
--- lldb/trunk/www/varformats.html (original)
+++ lldb/trunk/www/varformats.html Tue Aug 23 20:32:46 2011
@@ -1006,7 +1006,9 @@
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>
+ <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.
+ You may especially want to begin looking at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/StdVectorSynthProvider.py">StdVector</a> to get
+ a feel for this feature.</p>
<p>Once a synthetic children provider is written, one must load it into LLDB before it can be used.
Currently, one can use the LLDB <code>script</code> command to type Python code interactively,
@@ -1084,14 +1086,41 @@
</div>
</div>
-
+ <div class="post">
+ <h1 class="postheader">Categories</h1>
+ <div class="postcontent">
+ <p>Categories are a way to group related formatters. For instance, LLDB itself groups
+ the formatters for the C++ STL objects in a category named <code>gnu-libstdc++</code>.
+ Basically, categories act like containers in which to store formatters for a same library
+ or OS release.</p>
+ <p>By default, three categories are created in LLDB: <code>system</code>, <code>gnu-libstdc++</code> and <code>default</code>.
+ Every formatter that is not created inside a category, is by default a part of the <code>default</code> category.
+ If you want to use a custom category for your formatters, all the <code>type ... add</code> (except for <code>type format add</code>),
+ provide a <code>--category</code> (<code>-w</code>) option, that names the category to add the formatter to.
+ To delete the formatter, you then have to specify the correct category.</p>
+ <p>Categories can be in one of two states: enabled and disabled. A category is initially disabled,
+ and can be enabled using the <code>type category enable</code> command. To disable an enabled category,
+ the command to use is <code>type category disable</code>. The order in which categories are enabled or disabled
+ is significant, in that LLDB uses that order when looking for formatters. Therefore, when you enable a category, it becomes
+ the first one to be searched. The default categories are enabled in the order: <code>default</code> as first, then
+ <code>gnu-libstdc++</code>, and finally <code>system</code>. As said, <code>gnu-libstdc++</code> contains formatters for C++ STL
+ data types. <code>system</code> contains formatters for <code>char*</code> and <code>char[]</code>, which are expected to be
+ consistent throughout libraries and systems, and replace </p>
+ <p>Categories are a way to group related formatters. For instance, LLDB itself groups
+ the formatters for the C++ STL objects in a category named <code>gnu-libstdc++</code></p>
+ </div>
+ </div>
+
<div class="post">
<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), searching formatters for a type goes through
- a rather intricate set of rules. Namely, what happens is:</p>
+ a rather intricate set of rules. Namely, what happens is that LLDB
+ starts looking in each enabled category, according to the order in which
+ they were enabled (latest enabled first). In each category, LLDB does
+ the following:</p>
<ul>
<li>If there is a formatter for the type of the variable,
use it</li>
@@ -1125,6 +1154,11 @@
looking for regular expressions instead of exact
matches</li>
</ul>
+ <p>If any of those attempts returned a valid formatter to be used,
+ that one is used, and the search is terminated (without going to look
+ in other categories). If nothing was found in the current category, the next
+ enabled category is scanned according to the same algorithm. If there are no
+ more enabled categories, the search has failed.</p>
</div>
</div>
<div class="post">
More information about the lldb-commits
mailing list