RFA: Document @-frame variable objects

RFA: Document @-frame variable objects

[Jim Blandy]

Could the MI folks also read this over for accuracy?

gdb/doc/ChangeLog:
2007-05-25  Jim Blandy  <jimb@codesourcery.com>

	* gdb.texinfo (GDB/MI Variable Objects): Document @-frame variable
	objects.

Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.405
diff -u -r1.405 gdb.texinfo
--- gdb/doc/gdb.texinfo	16 May 2007 14:16:32 -0000	1.405
+++ gdb/doc/gdb.texinfo	25 May 2007 17:31:14 -0000
@@ -19250,7 +19250,7 @@
 
 @smallexample
  -var-create @{@var{name} | "-"@}
-    @{@var{frame-addr} | "*"@} @var{expression}
+    @{@var{frame-addr} | "*" | "@@"@} @var{expression}
 @end smallexample
 
 This operation creates a variable object, which allows the monitoring of
@@ -19263,12 +19263,33 @@
 unique provided that one does not specify @var{name} on that format.
 The command fails if a duplicate name is found.
 
-The frame under which the expression should be evaluated can be
-specified by @var{frame-addr}.  A @samp{*} indicates that the current
-frame should be used.
+The second argument indicates the scope in which GDB should evaluate
+@var{expression}:
+@itemize @bullet
+@item
+If it is @var{frame-addr}, then GDB finds a frame at that address in
+the current stack, and evaluates @var{expression} in that frame's
+scope.  When the frame is eventually popped, the variable object is
+marked out of scope.
+
+@item
+If it is @samp{*}, then GDB evaluates @var{expression} in the scope of
+the frame selected at the time the @code{-var-create} command is
+given.  When the frame is eventually popped, the variable object is
+marked out of scope.
+
+@item
+If it is @samp{@@}, then the expression has no fixed scope: GDB
+evaluates @var{expression} in the currently selected frame, and future
+@code{-var-update} commands will use whatever frame is selected when
+they are invoked.  Variable objects of this sort may go in and out of
+scope as the program runs, and their type may change from one update
+to the next.
+
+@end itemize
 
-@var{expression} is any expression valid on the current language set (must not
-begin with a @samp{*}), or one of the following:
+@var{expression} is any expression valid on the current language set
+(although it must not begin with a @samp{*}), or one of the following:
 
 @itemize @bullet
 @item

Re: RFA: Document @-frame variable objects

[Eli Zaretskii]

> From: Jim Blandy <jimb@codesourcery.com>
> Date: Fri, 25 May 2007 10:32:25 -0700
> 
> 
> Could the MI folks also read this over for accuracy?
> 
> gdb/doc/ChangeLog:
> 2007-05-25  Jim Blandy  <jimb@codesourcery.com>
> 
> 	* gdb.texinfo (GDB/MI Variable Objects): Document @-frame variable
> 	objects.

Approved, provided that the MI folks say it's accurate.

Thanks.

Re: RFA: Document @-frame variable objects

[Nick Roberts]

 > Could the MI folks also read this over for accuracy?

I've never tried to this behaviour because I've not used it yet, there are
many instance in the GDB manual where current and selected frame are confused,
and if the description isn't completely accurate it may get reported as a bug.

The manual currently says:

>    The frame under which the expression should be evaluated can be
> specified by FRAME-ADDR.  A `*' indicates that the current frame should
> be used.

Even this isn't true.  If you stop in a frame (current frame) then do "up",
you can no longer create variable objects in the current frame, but you
can create them in the selected frame.

 >...
 > +@item
 > +If it is @samp{*}, then GDB evaluates @var{expression} in the scope of
 > +the frame selected at the time the @code{-var-create} command is
 > +given.  

This sounds right.

 >          When the frame is eventually popped, the variable object is
 > +marked out of scope.

This is really part of "-var-update" and I've added something about scope
the manual already, although you might want to add to it.

 > +@item
 > +If it is @samp{@@}, then the expression has no fixed scope: GDB
 > +evaluates @var{expression} in the currently selected frame, and future
 > +@code{-var-update} commands will use whatever frame is selected when
 > +they are invoked.  Variable objects of this sort may go in and out of
 > +scope as the program runs, and their type may change from one update
 > +to the next.

I don't think this is accurate.  If you have two frames, where i=10 in
one and i=5 in the other, GDB won't report any change with -var-update
if you do "up" and "down" to move between them.

Note that thhere are probably many other deficiencies in the description of
MI, e.g,

   * `*ADDR-ADDR' -- a memory address range (TBD)

can't work because `*0x8049e54 - 3' gets evaluated by GDB as the value
at 0x8049e54 minus 3.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: RFA: Document @-frame variable objects

[Nick Roberts]

 >  > +@item
 >  > +If it is @samp{@@}, then the expression has no fixed scope: GDB
 >  > +evaluates @var{expression} in the currently selected frame, and future
 >  > +@code{-var-update} commands will use whatever frame is selected when
 >  > +they are invoked.  Variable objects of this sort may go in and out of
 >  > +scope as the program runs, and their type may change from one update
 >  > +to the next.
 > 
 > I don't think this is accurate.  If you have two frames, where i=10 in
 > one and i=5 in the other, GDB won't report any change with -var-update
 > if you do "up" and "down" to move between them.

Actually I'm confused now because GDB 6.6 seems to behave differently to GDB in
CVS.  In the latter, it does report changes, albeit with the wrong value in the
frame in which the varobj wasn't created.

I see that there is just one test for this type of varobj -- just for the
creation, in mi-var-cmd.exp and mi2-var-cmd.exp -- which explains why changes
haven't been noticed.  If we are serious about using @, then we really need to
check it's behavior and add more tests.

-- 
Nick                                           http://www.inet.net.nz/~nickrob