This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH 12/12] NEWS and Doc on --available-children-only
- From: Yao Qi <yao at codesourcery dot com>
- To: Eli Zaretskii <eliz at gnu dot org>
- Cc: <gdb-patches at sourceware dot org>
- Date: Mon, 17 Feb 2014 17:44:20 +0800
- Subject: Re: [PATCH 12/12] NEWS and Doc on --available-children-only
- Authentication-results: sourceware.org; auth=none
- References: <1392367471-13527-1-git-send-email-yao at codesourcery dot com> <1392367471-13527-13-git-send-email-yao at codesourcery dot com> <83ha82c9rf dot fsf at gnu dot org>
On 02/14/2014 05:40 PM, Eli Zaretskii wrote:
> This doesn't really say much about the new option, because what
> "available children" means is not explained at all. Can you add a
> sentence about that, or, better, reword this sentence
>
> When used, only the available children are displayed.
>
> so that the second part explains which children will be displayed and
> which won't?
IMO, "available children" is not a new term in GDB. We've already had
some in doc:
Note that this number is not completely reliable for a dynamic varobj.
It will return the current number of children, but more children may
^^^^^^^^^^^^
be available.
^^^^^^^^^^^^^
The @samp{numchild} field in other varobj responses is generally not
valid for a dynamic varobj -- it will show the number of children that
@value{GDBN} knows about, but because dynamic varobjs lazily
instantiate their children, this will not reflect the number of
children which may be available.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"available children" means children, whose values are available, or
value available children. How about replacing "available children"
with "value available children"? Is it clear?
>
>> > The number of children of the varobj. This number is not necessarily
>> > -reliable for a dynamic varobj. Instead, you must examine the
>> > -@samp{has_more} attribute.
>> > +reliable for a dynamic varobj or for a non-dynamic varobj if the
>> > +@samp{--available-children-only} option was specified.
> When --available-children-only is specified, isn't it true that this
> number is unreliable for _any_ varobj? If so, please rephrase to make
> that explicit.
>
OK. I mention that explicitly in doc.
>> > -For a dynamic varobj, this indicates whether there appear to be any
>> > -children available. For a non-dynamic varobj, this will be 0.
>> > +For a dynamic varobj, or for a non-dynamic varobj when the
>> > +@samp{--available-children-only} option is specified, this indicates
>> > +whether there appear to be more children that haven't been listed yet,
>> > +which can be listed with a following @code{-var-list-children}
>> > +command. For the other cases, this will be 0.
> Same here.
>
Fixed.
>> > +Note that this number is not completely reliable for a dynamic varobj
>> > +or for a non-dynamic varobj that is listing only available or
>> > +collected children. It will return the current number of children,
>> > +but more children may be available.
> And here.
>
Fixed.
>> > +If for a given varobj, the presence of the
>> > +@samp{--available-children-only} option changes between invocations of
>> > +the @code{-var-create}, @code{-var-list-children} or
>> > +@code{-var-info-num-children} commands, the list of children is
>> > +reinitialized.
> "Presence of the ... option changes" sounds awkward. Does this
> sentence say anything important? IOW, does reinitialization of the
> list of children have any user-visible effects? If not, perhaps it is
> better to delete it. If you think this is needed, then I'd rephrase
> like this:
IMO, it has user-visible effects, which describes the expected behaviour
of sequence "-var-create --available-children-only" and
"-var-list-children". This is important to MI front end.
>
> If you use any of the commands @code{-var-create},
> @code{-var-list-children}, or @code{-var-info-num-children} with the
> @samp{--available-children-only} option followed by any of these
> commands without that option, or vice versa, the list of children is
> reinitialized.
It is good to me. I'll pick it up.
>
>> > @smallexample
>> > - -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
>> > + -var-list-children
>> > + [--available-children-only]
>> > + [@var{print-values}] @var{name} [@var{from} @var{to}]
>> > @end smallexample
> Will the reader understand that this is one long line broken for
> readability? If not, perhaps you should tell that explicitly.
>
Oh, let us put them in a single line to avoid confusion.
>> > +If the @samp{--available-children-only} option is specified, then only
>> > +available or collected children of the varobj are considered.
> Once again, "available children" needs to be explained.
>
>> > +If for a given varobj, the presence of the
>> > +@samp{--available-children-only} option changes between invocations of
>> > +the @code{-var-create}, @code{-var-list-children} or
>> > +@code{-var-info-num-children} commands, the list of children is
>> > +reinitialized.
> Same comment as above.
>
>> > @item new_num_children
>> > -For a dynamic varobj, if the number of children changed, or if the
>> > -type changed, this will be the new number of children.
>> > +For a dynamic varobj, or non-dynamic varobj that had been created as
>> > +consequence of the @samp{--available-children-only} option to the
>> > +@code{-var-create}, @code{-var-list-children} or
>> > +@code{-var-info-num-children} commands, if the number of children
>> > +changed, or if the type changed, this will be the new number of
>> > +children.
> This sentence is now too long and complicated to be clear. Suggest to
> break into 2 sentences. E.g., leave the original sentence as is, and
> then add something like
>
> Similarly for a non-dynamic varobj that was created as result of the
> @samp{--available-children-only} option ...
>
Fixed as you suggested. How about the updated patch below?
--
Yao (éå)
gdb/doc:
2014-02-17 Pedro Alves <pedro@codesourcery.com>
Yao Qi <yao@codesourcery.com>
* gdb.texinfo (GDB/MI Variable Objects): Update doc of MI
commands "-var-create", "-var-info-num-children" and
"-var-list-children".
(GDB/MI Support Commands): Document the new
"available-children-only" entry in the output of the
"-list-features" command.
gdb:
2014-02-17 Yao Qi <yao@codesourcery.com>
* NEWS: Mention new option "--available-children-only".
---
gdb/NEWS | 7 +++++++
gdb/doc/gdb.texinfo | 47 +++++++++++++++++++++++++++++++++++++++++------
2 files changed, 48 insertions(+), 6 deletions(-)
diff --git a/gdb/NEWS b/gdb/NEWS
index 7fc3669..1eff6b3 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -90,6 +90,13 @@ PowerPC64 GNU/Linux little-endian powerpc64le-*-linux*
** The commands -break-passcount and -break-commands accept convenience
variable as breakpoint number.
+ ** The commands -var-create, -var-info-num-children and
+ -var-list-children now accept an option
+ "--available-children-only". When used, only the value available
+ children are displayed. Support for this feature can be verified
+ using the "-list-features" command, which should contain
+ "available-children-only".
+
*** Changes in GDB 7.7
* Improved support for process record-replay and reverse debugging on
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 035573e..03d395f 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -32504,7 +32504,7 @@ may work differently in future versions of @value{GDBN}.
@subsubheading Synopsis
@smallexample
- -var-create @{@var{name} | "-"@}
+ -var-create [--available-children-only] @{@var{name} | "-"@}
@{@var{frame-addr} | "*" | "@@"@} @var{expression}
@end smallexample
@@ -32526,6 +32526,11 @@ object must be created.
@var{expression} is any expression valid on the current language set (must not
begin with a @samp{*}), or one of the following:
+If the @samp{--available-children-only} option is specified, then only
+value available or collected children of the varobj are considered.
+This affects the @samp{numchild} and @samp{has_more} attributes in the
+output result.
+
@itemize @bullet
@item
@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
@@ -32557,7 +32562,8 @@ The name of the varobj.
@item numchild
The number of children of the varobj. This number is not necessarily
reliable for a dynamic varobj. Instead, you must examine the
-@samp{has_more} attribute.
+@samp{has_more} attribute. If the @samp{--available-children-only}
+option was specified, this number is not reliable either.
@item value
The varobj's scalar value. For a varobj whose type is some sort of
@@ -32577,7 +32583,9 @@ thread's identifier.
@item has_more
For a dynamic varobj, this indicates whether there appear to be any
-children available. For a non-dynamic varobj, this will be 0.
+children available. When the @samp{--available-children-only} option
+is specified, this indicates whether there appear to be more children
+that haven't been listed yet. For the other cases, this will be 0.
@item dynamic
This attribute will be present and have the value @samp{1} if the
@@ -32663,7 +32671,7 @@ Returns the format used to display the value of the object @var{name}.
@subsubheading Synopsis
@smallexample
- -var-info-num-children @var{name}
+ -var-info-num-children [--available-children-only] @var{name}
@end smallexample
Returns the number of children of a variable object @var{name}:
@@ -32672,10 +32680,20 @@ Returns the number of children of a variable object @var{name}:
numchild=@var{n}
@end smallexample
+If the @samp{--available-children-only} option is specified, then only
+value available or collected children of the varobj are considered.
+
Note that this number is not completely reliable for a dynamic varobj.
+When the @samp{--available-children-only} option is specified, this
+number is not reliable either for a varobj.
It will return the current number of children, but more children may
be available.
+If you use any of the commands @code{-var-create},
+@code{-var-list-children}, or @code{-var-info-num-children} with the
+@samp{--available-children-only} option followed by any of these
+commands without that option, or vice versa, the list of children is
+reinitialized.
@subheading The @code{-var-list-children} Command
@findex -var-list-children
@@ -32683,7 +32701,7 @@ be available.
@subsubheading Synopsis
@smallexample
- -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
+ -var-list-children [--available-children-only] [@var{print-values}] @var{name} [@var{from} @var{to}]
@end smallexample
@anchor{-var-list-children}
@@ -32712,6 +32730,15 @@ then the front end could call @code{-var-set-update-range} with a
different range to ensure that future updates are restricted to just
the visible items.
+If the @samp{--available-children-only} option is specified, then only
+value available or collected children of the varobj are considered.
+
+If you use any of the commands @code{-var-create},
+@code{-var-list-children}, or @code{-var-info-num-children} with the
+@samp{--available-children-only} option followed by any of these
+commands without that option, or vice versa, the list of children is
+reinitialized.
+
For each child the following results are returned:
@table @var
@@ -33022,7 +33049,10 @@ hold the new type.
@item new_num_children
For a dynamic varobj, if the number of children changed, or if the
-type changed, this will be the new number of children.
+type changed, this will be the new number of children. Similarly
+for a non-dynamic varobj that was created as result of the
+@samp{--available-children-only} option to the @code{-var-create},
+@code{-var-list-children} or @code{-var-info-num-children} commands.
The @samp{numchild} field in other varobj responses is generally not
valid for a dynamic varobj -- it will show the number of children that
@@ -35296,6 +35326,11 @@ records, produced when trying to execute an undefined @sc{gdb/mi} command
@item exec-run-start-option
Indicates that the @code{-exec-run} command supports the @option{--start}
option (@pxref{GDB/MI Program Execution}).
+@item available-children-only
+Indicates that the @code{-var-create}, @code{-var-info-num-children}
+and @code{-var-list-children} commands support the
+@option{--available-children-only}.
+
@end ftable
@subheading The @code{-list-target-features} Command
--
1.7.7.6