From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 2360 invoked by alias); 8 Jan 2007 20:09:48 -0000 Received: (qmail 2349 invoked by uid 22791); 8 Jan 2007 20:09:47 -0000 X-Spam-Check-By: sourceware.org Received: from zigzag.lvk.cs.msu.su (HELO zigzag.lvk.cs.msu.su) (158.250.17.23) by sourceware.org (qpsmtpd/0.31) with ESMTP; Mon, 08 Jan 2007 20:09:36 +0000 Received: from Debian-exim by zigzag.lvk.cs.msu.su with spam-scanned (Exim 4.50) id 1H40oB-00012t-FQ for gdb-patches@sources.redhat.com; Mon, 08 Jan 2007 23:09:32 +0300 Received: from localhost ([127.0.0.1] helo=ip6-localhost) by zigzag.lvk.cs.msu.su with esmtp (Exim 4.50) id 1H40o1-00012M-A3; Mon, 08 Jan 2007 23:09:17 +0300 From: Vladimir Prus Subject: Re: [doc] improve MI varobj introduction To: Eli Zaretskii , gdb-patches@sources.redhat.com Date: Mon, 08 Jan 2007 20:09:00 -0000 References: <200612191103.55137.vladimir@codesourcery.com> <200701051139.09498.ghost@cs.msu.su> User-Agent: KNode/0.10.2 MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="nextPart8296953.J7fNUDog3r" Content-Transfer-Encoding: 7Bit Message-Id: 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 X-SW-Source: 2007-01/txt/msg00241.txt.bz2 --nextPart8296953.J7fNUDog3r Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8Bit Content-length: 2611 Eli Zaretskii wrote: >> From: Vladimir Prus >> Date: Mon, 08 Jan 2007 17:49:12 +0300 >> > >> > Variable objects are an MI convenience feature to reference >> > expressions. When a frontend creates a variable object, it >> > specifies a name for an arbitrary expression in the debugged >> > program. That name can henceforth be used as an opaque handle for >> > the expression. The expression can be a simple variable, or it can >> > be ... >> > >> > Okay? >> >> You're right that my text did not say why it's recommended, but I think >> the above is also not accurate. "convenient feature to reference >> expressions" is not quite right -- it sounds like varobj is just a method >> to create aliases for expression, and varobjs are much more than that. >> How about: >> >> Variable objects are "object-oriented" MI interface for >> examining and changing values of expressions. Unlike some other >> MI interfaces that work with expressions, variable objects are >> specifically designed for simple and efficient >> presentation in the frontend. A variable object is identified >> by string name. When a variable object is created, the >> frontend specifies the expression for that variable object. >> The expression can be a simple variable ........ > > The first two sentences sound to me more like advertisement, but if > you feel you need to say that, fine. Yes, I feel we need to emphasise that varobjs is what folks should use, not some convenience that might be ignored. > >> > A child variable object can itself have children, until we reach >> > leaf variable objects which have built-in types. >> >> That looks fine for me, but should not we have a command before "which"? >> Otherwise, it sounds like there are two kind of leaf variable objects -- >> those of builtin types and those of non-builtin types. > > I just tried to make a minimal modification of your text. Perhaps a > better variant is this: > > A child variable object can itself have children, recursively. > Recursion ends when we reach leaf variable objects that have > built-in types. Again, "that have built-in types" sounds to me like restrictive clause, as if there are leaf variables that don't have builtin-types. What about: Recursion ends when we reach leaf variable objects, which always have built-in types. I attach the revised patch, incorporating those two corrections, and using the above last sentence. Is it OK, or would you prefer your original sentence? Thanks, Volodya --nextPart8296953.J7fNUDog3r Content-Type: text/x-diff; name="varobj_doc__gdb_mainline.diff" Content-Transfer-Encoding: 8Bit Content-Disposition: attachment; filename="varobj_doc__gdb_mainline.diff" Content-length: 5883 --- gdb/doc/gdb.texinfo (/patches/gdb/mi_inline_tests/gdb_mainline) (revision 3074) +++ gdb/doc/gdb.texinfo (/patches/gdb/varobj_doc/gdb_mainline) (revision 3074) @@ -19570,26 +19570,40 @@ least, the following operations: @end ignore -@subheading Introduction to Variable Objects in @sc{gdb/mi} +@subheading Introduction to Variable Objects @cindex variable objects in @sc{gdb/mi} -The basic idea behind variable objects is the creation of a named object -to represent a variable, an expression, a memory location or even a CPU -register. For each object created, a set of operations is available for -examining or changing its properties. - -Furthermore, complex data types, such as C structures, are represented -in a tree format. For instance, the @code{struct} type variable is the -root and the children will represent the struct members. If a child -is itself of a complex type, it will also have children of its own. -Appropriate language differences are handled for C, C@t{++} and Java. - -When returning the actual values of the objects, this facility allows -for the individual selection of the display format used in the result -creation. It can be chosen among: binary, decimal, hexadecimal, octal -and natural. Natural refers to a default format automatically -chosen based on the variable type (like decimal for an @code{int}, hex -for pointers, etc.). + +Variable objects are "object-oriented" MI interface for examining and +changing values of expressions. Unlike some other MI interfaces that +work with expressions, variable objects are specifically designed for +simple and efficient presentation in the frontend. A variable object +is identified by string name. When a variable object is created, the +frontend specifies the expression for that variable object. The +expression can be a simple variable, or it can be an arbitrary complex +expression, and can even involve CPU registers. After creating a +variable object, the frontend can invoke other variable object +operations---for example to obtain or change the value of a variable +object, or to change display format. + +Variable objects have hierarchical tree structure. Any variable object +that corresponds to a composite type, such as structure in C, has +a number of child variable objects, for example corresponding to each +element of a structure. A child variable object can itself have +children, recursively. Recursion ends when we reach +leaf variable objects, which always have built-in types. + +For a leaf variable object it is possible to obtain its value as a +string, or set the value from a string. String value can be also +obtained for a non-leaf variable object, but it's generally a string +that only indicates the type of the object, and does not list its +contents. Assignment to a non-leaf variable object is not allowed. + +A frontend does not need to read the values of all variable objects each time +the program stops. Instead, MI provides an update command that lists all +variable objects whose values has changed since the last update +operation. This considerably reduces the amount of data that must +be transferred to the frontend. The following is the complete set of @sc{gdb/mi} operations defined to access this functionality: @@ -19712,6 +19726,12 @@ The syntax for the @var{format-spec} is @{binary | decimal | hexadecimal | octal | natural@} @end smallexample +The natural format is the default format choosen automatically +based on the variable type (like decimal for an @code{int}, hex +for pointers, etc.). + +For a variable with children, the format is set only on the +variable itself, and the children are not affected. @subheading The @code{-var-show-format} Command @findex -var-show-format @@ -19843,8 +19863,8 @@ where @var{attr} is @code{@{ @{ editable @end smallexample Evaluates the expression that is represented by the specified variable -object and returns its value as a string in the current format specified -for the object: +object and returns its value as a string. The format of the +string can be changed using the @code{-var-set-format} command. @smallexample value=@var{value} @@ -19888,12 +19908,19 @@ subsequent @code{-var-update} list. -var-update [@var{print-values}] @{@var{name} | "*"@} @end smallexample -Update the value of the variable object @var{name} by evaluating its -expression after fetching all the new values from memory or registers. -A @samp{*} causes all existing variable objects to be updated. The -option @var{print-values} determines whether names both and values, or -just names are printed in the manner described for -@code{-var-list-children} (@pxref{-var-list-children}). +Reevaluate the expressions corresponding to the variable object +@var{name} and all its direct and indirect children, and return the +list of variable objects whose values have changed. Here, +``changed'' means that the result of @code{-var-evaluate-expression} before +and after the @code{-var-update} is different. If @samp{*} is used +as the variable object names, all existing variable objects are +updated. The option @var{print-values} determines whether both names +and values, or just names are printed. The possible values of +this options are the same as for @code{-var-list-children} +(@pxref{-var-list-children}). It is recommended to use the +@samp{--all-values} option, to reduce the number of MI commands needed +on each program stop. + @subsubheading Example Property changes on: ___________________________________________________________________ Name: csl:base -/all/patches/gdb/mi_continue_to/gdb_mainline +/all/patches/gdb/mi_inline_tests/gdb_mainline Name: svk:merge d48a11ec-ee1c-0410-b3f5-c20844f99675:/patches/gdb/mi_continue_to/gdb_mainline:2736 +d48a11ec-ee1c-0410-b3f5-c20844f99675:/patches/gdb/mi_inline_tests/gdb_mainline:3051 --nextPart8296953.J7fNUDog3r--