[RFA] Document fixed/floating variable objects and thread-id.

[RFA] Document fixed/floating variable objects and thread-id.

[Vladimir Prus]

This patch adds some more docs about variable objects. Even
though floating variable objects have know bugs, I think their
intended behaviour is sufficiently clear right now to document.

- Volodya

	* gdb/doc/gdb.texinfo (gdb/mi Variable object): Document
	fixed and floating variable objects, and clarify that
	a variable object can also be found to a thread.  Update
	-var-create example.
---
 gdb/doc/gdb.texinfo |   32 +++++++++++++++++++++++++-------
 1 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index c73a6d9..4c0b3b9 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -19900,7 +19900,23 @@ relatively slow for embedded targets, so a frontend might want
 to disable automatic update for the variables that are either not
 visible on the screen, or ``closed''.  This is possible using so
 called ``frozen variable objects''.  Such variable objects are never
-implicitly updated.  
+implicitly updated.
+
+Variable objects can be either ``fixed'' or ``floating''. For the
+fixed variable object, the expression is parsed when the variable
+object is created, including associating indentifiers to specific
+variables.  The meaning of expression never changes.  A floating 
+variable object has its expression reparsed each time the variable
+object is updated.  In particular, the meaning of identifiers can
+change every time.
+
+If an expression specified when creating a fixed variable object
+refers to a local variable, the variable object becomes bound to the 
+frame the local variable belongs to.  For multithreaded programs, the
+variable object also becomes bound to the thread.  When such variable
+object is updated, @value{GDBN} makes sure that the thread/frame
+combination the variable object is bound to still exists, and
+re-evaluates the variable object in that thread/frame.
 
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
@@ -19951,7 +19967,7 @@ how it can be used.
 
 @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
@@ -19961,12 +19977,13 @@ register.
 The @var{name} parameter is the string by which the object can be
 referenced.  It must be unique.  If @samp{-} is specified, the varobj
 system will generate a string ``varNNNNNN'' automatically.  It will be
-unique provided that one does not specify @var{name} on that format.
-The command fails if a duplicate name is found.
+unique provided that one does not explicitly specifies @var{name} of
+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.
+frame should be used. A @samp{*} indicates that a floating variable
+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:
@@ -19986,10 +20003,11 @@ begin with a @samp{*}), or one of the following:
 
 This operation returns the name, number of children and the type of the
 object created.  Type is returned as a string as the ones generated by
-the @value{GDBN} CLI:
+the @value{GDBN} CLI.  If a fixed variable object is bound to a
+specific thread, the thread is is also printed:
 
 @smallexample
- name="@var{name}",numchild="N",type="@var{type}"
+ name="@var{name}",numchild="N",type="@var{type}",thread-id="M"
 @end smallexample
 
 
-- 
1.5.3.5

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Fri, 4 Apr 2008 13:20:00 +0400
> 
> 
> This patch adds some more docs about variable objects.

Thanks, adding documentation is always welcome.

> 	* gdb/doc/gdb.texinfo (gdb/mi Variable object): Document
> 	fixed and floating variable objects, and clarify that
> 	a variable object can also be found to a thread.  Update
> 	-var-create example.

Some comments and suggestions:

> +Variable objects can be either ``fixed'' or ``floating''. For the

Texinfo has a special markup for introducing new terminology: @dfn.
So please use @dfn{fixed} and @dfn{floating}, as it looks better in
print.

Also, there's only one blank after the end of the sentence here;
please use two.

> +fixed variable object, the expression is parsed when the variable
> +object is created, including associating indentifiers to specific
> +variables.  The meaning of expression never changes.  A floating 
> +variable object has its expression reparsed each time the variable
> +object is updated.  In particular, the meaning of identifiers can
> +change every time.

Instead of ``meaning'' here, isn't it better to say ``value''?

Other than that, this is approved, thanks.

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Daniel Jacobowitz]

On Fri, Apr 04, 2008 at 01:20:00PM +0400, Vladimir Prus wrote:
> 
> This patch adds some more docs about variable objects. Even
> though floating variable objects have know bugs, I think their
> intended behaviour is sufficiently clear right now to document.
> 
> - Volodya
> 
> 	* gdb/doc/gdb.texinfo (gdb/mi Variable object): Document
> 	fixed and floating variable objects, and clarify that
> 	a variable object can also be found to a thread.  Update
> 	-var-create example.

There's also this patch, if you want to grab any text from it:

  http://sourceware.org/ml/gdb-patches/2007-05/msg00397.html

I noticed that he used "@@", which is probably correct; you had
"@" and I think texinfo will take that as an operator.

> -unique provided that one does not specify @var{name} on that format.
> -The command fails if a duplicate name is found.
> +unique provided that one does not explicitly specifies @var{name} of
> +that format.  The command fails if a duplicate name is found.
>  

"specify" from the original text was correct; "on" was not, nice catch.

>  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.
> +frame should be used. A @samp{*} indicates that a floating variable
> +object must be created.

Two spaces.


-- 
Daniel Jacobowitz
CodeSourcery

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Pedro Alves]

A Friday 04 April 2008 10:20:00, Vladimir Prus wrote:

> +Variable objects can be either ``fixed'' or ``floating''. For the
> +fixed variable object, the expression is parsed when the variable
> +object is created, including associating indentifiers to specific

identifiers.

-- 
Pedro Alves

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Vladimir Prus]

Eli Zaretskii wrote:

>> From: Vladimir Prus <vladimir@codesourcery.com>
>> Date: Fri, 4 Apr 2008 13:20:00 +0400
>> 
>> 
>> This patch adds some more docs about variable objects.
> 
> Thanks, adding documentation is always welcome.
> 
>> * gdb/doc/gdb.texinfo (gdb/mi Variable object): Document
>> fixed and floating variable objects, and clarify that
>> a variable object can also be found to a thread.  Update
>> -var-create example.
> 
> Some comments and suggestions:
> 
>> +Variable objects can be either ``fixed'' or ``floating''. For the
> 
> Texinfo has a special markup for introducing new terminology: @dfn.
> So please use @dfn{fixed} and @dfn{floating}, as it looks better in
> print.
> 
> Also, there's only one blank after the end of the sentence here;
> please use two.
> 
>> +fixed variable object, the expression is parsed when the variable
>> +object is created, including associating indentifiers to specific
>> +variables.  The meaning of expression never changes.  A floating
>> +variable object has its expression reparsed each time the variable
>> +object is updated.  In particular, the meaning of identifiers can
>> +change every time.
> 
> Instead of ``meaning'' here, isn't it better to say ``value''?

Identifier does not have a value. Think of 'i' -- it's just a name.
It is then associated to a specific variable, which variable has value.
What I mean is that association between identifiers to variables can
change for floating variable objects. Of course, the values can also
change, but values can change even for fixed variable objects.

What's the best way to express this?

- Volodya

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Eli Zaretskii]

> From:  Vladimir Prus <ghost@cs.msu.su>
> Date:  Wed, 09 Apr 2008 15:59:14 +0400
> 
> >> +fixed variable object, the expression is parsed when the variable
> >> +object is created, including associating indentifiers to specific
> >> +variables.  The meaning of expression never changes.  A floating
> >> +variable object has its expression reparsed each time the variable
> >> +object is updated.  In particular, the meaning of identifiers can
> >> +change every time.
> > 
> > Instead of ``meaning'' here, isn't it better to say ``value''?
> 
> Identifier does not have a value. Think of 'i' -- it's just a name.
> It is then associated to a specific variable, which variable has value.
> What I mean is that association between identifiers to variables can
> change for floating variable objects. Of course, the values can also
> change, but values can change even for fixed variable objects.
> 
> What's the best way to express this?

I don't know yet: what is an ``identifier'' in this context?  You
don't mean symbols in the source language of the program being
debugged, as in your example with `i', do you?

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Vladimir Prus]

On Wednesday 09 April 2008 19:00:28 Eli Zaretskii wrote:
> > From:  Vladimir Prus <ghost@cs.msu.su>
> > Date:  Wed, 09 Apr 2008 15:59:14 +0400
> > 
> > >> +fixed variable object, the expression is parsed when the variable
> > >> +object is created, including associating indentifiers to specific
> > >> +variables.  The meaning of expression never changes.  A floating
> > >> +variable object has its expression reparsed each time the variable
> > >> +object is updated.  In particular, the meaning of identifiers can
> > >> +change every time.
> > > 
> > > Instead of ``meaning'' here, isn't it better to say ``value''?
> > 
> > Identifier does not have a value. Think of 'i' -- it's just a name.
> > It is then associated to a specific variable, which variable has value.
> > What I mean is that association between identifiers to variables can
> > change for floating variable objects. Of course, the values can also
> > change, but values can change even for fixed variable objects.
> > 
> > What's the best way to express this?
> 
> I don't know yet: what is an ``identifier'' in this context?  You
> don't mean symbols in the source language of the program being
> debugged, as in your example with `i', do you?

I mean exactly that. variable object is created for an expression.
That expression, among other things, has identifiers that are resolved
to refer to variables in the program.

- Volodya

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Eli Zaretskii]

> From: Vladimir Prus <ghost@cs.msu.su>
> Date: Wed, 9 Apr 2008 19:10:56 +0400
> Cc: gdb-patches@sources.redhat.com
> 
> On Wednesday 09 April 2008 19:00:28 Eli Zaretskii wrote:
> > > From:  Vladimir Prus <ghost@cs.msu.su>
> > > Date:  Wed, 09 Apr 2008 15:59:14 +0400
> > > 
> > > >> +fixed variable object, the expression is parsed when the variable
> > > >> +object is created, including associating indentifiers to specific
> > > >> +variables.  The meaning of expression never changes.  A floating
> > > >> +variable object has its expression reparsed each time the variable
> > > >> +object is updated.  In particular, the meaning of identifiers can
> > > >> +change every time.
> > > > 
> > > > Instead of ``meaning'' here, isn't it better to say ``value''?
> > > 
> > > Identifier does not have a value. Think of 'i' -- it's just a name.
> > > It is then associated to a specific variable, which variable has value.
> > > What I mean is that association between identifiers to variables can
> > > change for floating variable objects. Of course, the values can also
> > > change, but values can change even for fixed variable objects.
> > > 
> > > What's the best way to express this?
> > 
> > I don't know yet: what is an ``identifier'' in this context?  You
> > don't mean symbols in the source language of the program being
> > debugged, as in your example with `i', do you?
> 
> I mean exactly that. variable object is created for an expression.
> That expression, among other things, has identifiers that are resolved
> to refer to variables in the program.

Then how about ``the values of variables whose names appear in the
expressions are re-evaluated every time''?

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Vladimir Prus]

On Wednesday 09 April 2008 21:05:39 Eli Zaretskii wrote:
> > From: Vladimir Prus <ghost@cs.msu.su>
> > Date: Wed, 9 Apr 2008 19:10:56 +0400
> > Cc: gdb-patches@sources.redhat.com
> > 
> > On Wednesday 09 April 2008 19:00:28 Eli Zaretskii wrote:
> > > > From:  Vladimir Prus <ghost@cs.msu.su>
> > > > Date:  Wed, 09 Apr 2008 15:59:14 +0400
> > > > 
> > > > >> +fixed variable object, the expression is parsed when the variable
> > > > >> +object is created, including associating indentifiers to specific
> > > > >> +variables.  The meaning of expression never changes.  A floating
> > > > >> +variable object has its expression reparsed each time the variable
> > > > >> +object is updated.  In particular, the meaning of identifiers can
> > > > >> +change every time.
> > > > > 
> > > > > Instead of ``meaning'' here, isn't it better to say ``value''?
> > > > 
> > > > Identifier does not have a value. Think of 'i' -- it's just a name.
> > > > It is then associated to a specific variable, which variable has value.
> > > > What I mean is that association between identifiers to variables can
> > > > change for floating variable objects. Of course, the values can also
> > > > change, but values can change even for fixed variable objects.
> > > > 
> > > > What's the best way to express this?
> > > 
> > > I don't know yet: what is an ``identifier'' in this context?  You
> > > don't mean symbols in the source language of the program being
> > > debugged, as in your example with `i', do you?
> > 
> > I mean exactly that. variable object is created for an expression.
> > That expression, among other things, has identifiers that are resolved
> > to refer to variables in the program.
> 
> Then how about ``the values of variables whose names appear in the
> expressions are re-evaluated every time''?

I'm afraid that this statement is true for fixed variable objects too,
and it still makes it sound like we pick variables, and then reevaluate it.
Instead, we reparse entire expression which can find completely different
variables.

- Volodya

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Eli Zaretskii]

> From: Vladimir Prus <ghost@cs.msu.su>
> Date: Wed, 9 Apr 2008 21:47:35 +0400
> Cc: gdb-patches@sources.redhat.com
> 
> > Then how about ``the values of variables whose names appear in the
> > expressions are re-evaluated every time''?
> 
> I'm afraid that this statement is true for fixed variable objects too,
> and it still makes it sound like we pick variables, and then reevaluate it.
> Instead, we reparse entire expression which can find completely different
> variables.

Well, I'm afraid I don't understand what you mean.  Please show me an
example where reparsing an expression would yield something different
each time.

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Vladimir Prus]

On Thursday 10 April 2008 00:52:01 Eli Zaretskii wrote:
> > From: Vladimir Prus <ghost@cs.msu.su>
> > Date: Wed, 9 Apr 2008 21:47:35 +0400
> > Cc: gdb-patches@sources.redhat.com
> > 
> > > Then how about ``the values of variables whose names appear in the
> > > expressions are re-evaluated every time''?
> > 
> > I'm afraid that this statement is true for fixed variable objects too,
> > and it still makes it sound like we pick variables, and then reevaluate it.
> > Instead, we reparse entire expression which can find completely different
> > variables.
> 
> Well, I'm afraid I don't understand what you mean.  Please show me an
> example where reparsing an expression would yield something different
> each time.

void foo (int i)
{
	...
}

void bar (int i)
{
	...
}


If you create a fixed varobj in 'bar', then each time you updating, new value of
bar's i will be read. If you create a floating varobj in 'bar', then if you update
it while still in bar, new value of bar's i will be read. If you update it in foo,
then the value of foo's i will be used. 

So while for fixed varobj's update fetches new value of 'i', for floating varobjs
we also decide which 'i' to use each time.

- Volodya

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Vladimir Prus]

Vladimir Prus wrote:

> On Thursday 10 April 2008 00:52:01 Eli Zaretskii wrote:
>> > From: Vladimir Prus <ghost@cs.msu.su>
>> > Date: Wed, 9 Apr 2008 21:47:35 +0400
>> > Cc: gdb-patches@sources.redhat.com
>> > 
>> > > Then how about ``the values of variables whose names appear in the
>> > > expressions are re-evaluated every time''?
>> > 
>> > I'm afraid that this statement is true for fixed variable objects too,
>> > and it still makes it sound like we pick variables, and then reevaluate it.
>> > Instead, we reparse entire expression which can find completely different
>> > variables.
>> 
>> Well, I'm afraid I don't understand what you mean.  Please show me an
>> example where reparsing an expression would yield something different
>> each time.
> 
> void foo (int i)
> {
> ...
> }
> 
> void bar (int i)
> {
> ...
> }
> 
> 
> If you create a fixed varobj in 'bar', then each time you updating, new value of
> bar's i will be read. If you create a floating varobj in 'bar', then if you update
> it while still in bar, new value of bar's i will be read. If you update it in foo,
> then the value of foo's i will be used.
> 
> So while for fixed varobj's update fetches new value of 'i', for floating varobjs
> we also decide which 'i' to use each time.

Eli,
does the above make the code behaviour clear enough for you to suggest better doc
working, or you want something else clarified?

Thanks,
Volodya

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Wed, 23 Apr 2008 14:26:14 +0400
> 
> > void foo (int i)
> > {
> > ...
> > }
> > 
> > void bar (int i)
> > {
> > ...
> > }
> > 
> > 
> > If you create a fixed varobj in 'bar', then each time you updating, new value of
> > bar's i will be read. If you create a floating varobj in 'bar', then if you update
> > it while still in bar, new value of bar's i will be read. If you update it in foo,
> > then the value of foo's i will be used.
> > 
> > So while for fixed varobj's update fetches new value of 'i', for floating varobjs
> > we also decide which 'i' to use each time.
> 
> Eli,
> does the above make the code behaviour clear enough for you to suggest better doc
> working, or you want something else clarified?

Sorry, I somehow was certain I replied to you back then, but I see now
that I didn't.

More to the point, I cannot say that I have a clear understanding of
the issue.  In what other situations will fixed and floating varobjs
behave differently?  Are we talking about any situation where
identically named variables have different binding to memory
addresses, depending on scope and context?  Like, for example,
identically named members of different C++ classes?  Or are we talking
about something else?

Also, why does such behavior make sense?  That is, why would I want an
object whose value depends on semi-random factors?  E.g., if the
inferior stopped at a watchpoint, the context is unpredictable, and
then so is the value of a floating varobj, if I understand you
correctly.  How is this helpful?

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Vladimir Prus]

Eli Zaretskii wrote:

>> From: Vladimir Prus <vladimir@codesourcery.com>
>> Date: Wed, 23 Apr 2008 14:26:14 +0400
>> 
>> > void foo (int i)
>> > {
>> > ...
>> > }
>> > 
>> > void bar (int i)
>> > {
>> > ...
>> > }
>> > 
>> > 
>> > If you create a fixed varobj in 'bar', then each time you updating, new value of
>> > bar's i will be read. If you create a floating varobj in 'bar', then if you update
>> > it while still in bar, new value of bar's i will be read. If you update it in foo,
>> > then the value of foo's i will be used.
>> > 
>> > So while for fixed varobj's update fetches new value of 'i', for floating varobjs
>> > we also decide which 'i' to use each time.
>> 
>> Eli,
>> does the above make the code behaviour clear enough for you to suggest better doc
>> working, or you want something else clarified?
> 
> Sorry, I somehow was certain I replied to you back then, but I see now
> that I didn't.
> 
> More to the point, I cannot say that I have a clear understanding of
> the issue.  In what other situations will fixed and floating varobjs
> behave differently?  Are we talking about any situation where
> identically named variables have different binding to memory
> addresses, depending on scope and context?  

Yes.

> Like, for example, 
> identically named members of different C++ classes?  

This is one possible example, but not the primary one, see below.

> Also, why does such behavior make sense?  That is, why would I want an
> object whose value depends on semi-random factors?  E.g., if the
> inferior stopped at a watchpoint, the context is unpredictable, and
> then so is the value of a floating varobj, if I understand you
> correctly.  How is this helpful?

One example is that you have function 'foo' that has a very important
variable 'foo_state' that you always want to see when you're inside
'foo'. The 'foo' function might be recursive, or it might be used in
different threads. With floating variable objects, when you switch
a thread or frame, you can update variable object, and see the value
of 'foo_state' in the current thread/frame. With fixed variable object,
you'd have to delete and create a variable object. In this case,
while 'foo_state' will always resolve to the same variable declaration
in the source code, the address of the variable will be different each
time.

It's possible to imagine cases where an identifier can be resolved to
different declaration each time a variable object is updated. For example,
you might have a convention that all classes have a 'str' method that
give a textual rendition of its state, even though those classes are not
necessary in a common hierarchy. By creating a floating varobj for 'str()'
expression you'll make that textual rendition show up.

- Volodya

Re: [RFA] Document fixed/floating variable objects and thread-id.

[Eli Zaretskii]

> From:  Vladimir Prus <vladimir@codesourcery.com>
> Date:  Sat, 26 Apr 2008 21:16:01 +0400
> 
> > More to the point, I cannot say that I have a clear understanding of
> > the issue.  In what other situations will fixed and floating varobjs
> > behave differently?  Are we talking about any situation where
> > identically named variables have different binding to memory
> > addresses, depending on scope and context?  
> 
> Yes.

Okay, thanks for explaining this to me.  Based on what you wrote, I
suggest to say ``the values of variables whose names appear in the
expressions are re-evaluated every time in the context of the current
frame.''  Adding a couple of examples might explain this even further.