From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 31194 invoked by alias); 17 Feb 2014 09:46:17 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 31181 invoked by uid 89); 17 Feb 2014 09:46:16 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.6 required=5.0 tests=AWL,BAYES_00 autolearn=ham version=3.3.2 X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 17 Feb 2014 09:46:15 +0000 Received: from svr-orw-exc-10.mgc.mentorg.com ([147.34.98.58]) by relay1.mentorg.com with esmtp id 1WFKmB-0004qe-8F from Yao_Qi@mentor.com ; Mon, 17 Feb 2014 01:46:11 -0800 Received: from SVR-ORW-FEM-02.mgc.mentorg.com ([147.34.96.206]) by SVR-ORW-EXC-10.mgc.mentorg.com with Microsoft SMTPSVC(6.0.3790.4675); Mon, 17 Feb 2014 01:46:11 -0800 Received: from qiyao.dyndns.org (147.34.91.1) by svr-orw-fem-02.mgc.mentorg.com (147.34.96.168) with Microsoft SMTP Server id 14.2.247.3; Mon, 17 Feb 2014 01:46:09 -0800 Message-ID: <5301D9F4.5010306@codesourcery.com> Date: Mon, 17 Feb 2014 09:46:00 -0000 From: Yao Qi User-Agent: Mozilla/5.0 (X11; Linux i686; rv:17.0) Gecko/20130110 Thunderbird/17.0.2 MIME-Version: 1.0 To: Eli Zaretskii CC: Subject: Re: [PATCH 12/12] NEWS and Doc on --available-children-only References: <1392367471-13527-1-git-send-email-yao@codesourcery.com> <1392367471-13527-13-git-send-email-yao@codesourcery.com> <83ha82c9rf.fsf@gnu.org> In-Reply-To: <83ha82c9rf.fsf@gnu.org> Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit X-IsSubscribed: yes X-SW-Source: 2014-02/txt/msg00531.txt.bz2 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 Yao Qi * 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 * 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