From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 20318 invoked by alias); 19 Dec 2006 08:04:37 -0000 Received: (qmail 20308 invoked by uid 22791); 19 Dec 2006 08:04:35 -0000 X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.4) by sourceware.org (qpsmtpd/0.31) with ESMTP; Tue, 19 Dec 2006 08:04:30 +0000 Received: (qmail 17986 invoked from network); 19 Dec 2006 08:04:27 -0000 Received: from unknown (HELO 172.16.unknown.plus.ru) (vladimir@127.0.0.2) by mail.codesourcery.com with ESMTPA; 19 Dec 2006 08:04:27 -0000 From: Vladimir Prus To: gdb-patches@sources.redhat.com Subject: [doc] improve MI varobj introduction Date: Tue, 19 Dec 2006 08:04:00 -0000 User-Agent: KMail/1.9.1 MIME-Version: 1.0 Content-Type: Multipart/Mixed; boundary="Boundary-00=_rz5hFlv42hjDUOo" Message-Id: <200612191103.55137.vladimir@codesourcery.com> 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: 2006-12/txt/msg00251.txt.bz2 --Boundary-00=_rz5hFlv42hjDUOo Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Content-Disposition: inline Content-length: 846 Hello, I think that at the moment, the introduction for varobj has a number of problems: - It does not mention update operation, which is 50% of varobjs relevance - It does not adequately describe hierarchy of varobjs, in particular that only leaf varobjs hold real data and can be manipulated. - There's a paragraph about hex/decimal format, which is minor detail and need not be mentioned. - The grammar of the text is overly complex sometimes. The attached patch basically rewrites the introduction. The semantic of -var-update is also clarified. The new introduction is basically one blob of text. There are places where docbook would be appropriate, but it looks to be not supported in info. Comments? - Volodya * gdb.texinfo (GDB/MI Variable Objects): Improve the introduction. Specify -var-update more exactly. --Boundary-00=_rz5hFlv42hjDUOo Content-Type: text/x-diff; charset="us-ascii"; name="varobj_doc__gdb_mainline.diff" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="varobj_doc__gdb_mainline.diff" Content-length: 4280 --- gdb/doc/gdb.texinfo (/mirrors/gdb_mainline) (revision 2727) +++ gdb/doc/gdb.texinfo (/patches/gdb/varobj_doc/gdb_mainline) (revision 2727) @@ -19570,26 +19570,36 @@ 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 object is MI interface to work with expressions. When +creating a variable object, a frontend specifies the name of +the variable object and an expression in the debugged program. +Such 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, a frontend can invoke other variable +object operations -- for example to obtain or change the value of +a variable object, or to change format. + +Variable objects have hierarchical 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. Child variable objects can children themself, +util we reach leaf variable objects of 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 its generally a string +that only indicates the type of the object, and does not list its +content. Assignment to a non-leaf variable object is not allowed. + +A frontend need not read the values of all variable objects each time +the program stops. Instead, MI provides update command that lists all +variable objects which 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: @@ -19888,12 +19898,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 object which values has changed as the result. 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 --Boundary-00=_rz5hFlv42hjDUOo--