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

Vladimir Prus
2008-04-04T09:26:15Z

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