Re: [PATCH] Per-inferior thread IDs

[Pedro Alves <palves at redhat dot com>]

On 12/17/2015 04:54 PM, Eli Zaretskii wrote:
>> Date: Thu, 17 Dec 2015 13:17:04 +0000
>> From: Pedro Alves <palves@redhat.com>
>> CC: gdb-patches@sourceware.org
>>
>> On 12/15/2015 07:39 PM, Eli Zaretskii wrote:
>>>> From: Pedro Alves <palves@redhat.com>
>>>> Date: Tue, 15 Dec 2015 19:05:16 +0000
>>>>
>>>> +See @xref{Convenience Vars,, Convenience Variables}, for general
>>>
>>> Either "See @ref" or just "@xref" (which will produce "See").
>>
>> Good catch, thanks.  I copied that mistake from the $_thread documentation.
>> Also, I realized that $_thread was not documented in the Convenience Vars
>> node.  I fixed that now, and also mentioned the new $_inferior/$_gthread
>> variables there.
> 
> Thanks.
> 
>>> Other than that, the documentation parts are OK, with one comment: it
>>> seems confusing to talk about "per-inferior ID" when evidently you
>>> refer to the 2.3 form of the thread ID.  Can we find some other term
>>> for this ID?
>>
>> You're right.  How about per-inferior number to refer to the number
>> in the inferior, and use thread ID to generically refer to the
>> inferior num + thread num pair?
> 
> Sounds good to me, thanks.
> 
> I have a few minor comments:
> 
>> +* Per-inferior thread numbers
>> +
>> +  Thread numbers are now per inferior instead of global.  If you're
>> +  debugging multiple inferiors, GDB displays thread IDs using an
>> +  expanded INF_NUM.THR_NUM form.  For example:
> 
> Suggest to use "qualified" instead of "expanded" here, so that the
> next text:

Done.

> 
>> +     (gdb) info threads
>> +       Id   Target Id         Frame
>> +       1.1  Thread 0x7ffff7fc2740 (LWP 8155) (running)
>> +       1.2  Thread 0x7ffff7fc1700 (LWP 8168) (running)
>> +     * 2.1  Thread 0x7ffff7fc2740 (LWP 8157) (running)
>> +       2.2  Thread 0x7ffff7fc1700 (LWP 8190) (running)
>> +
>> +  Commands that accept thread IDs now accept the qualified form as
>> +  well:                                          ^^^^^^^^^^^^^^
> 
> will use the same terminology.
> 
>> +
>> +     (gdb) thread 2.1
>> +     [Switching to thread 2.1 (Thread 0x7ffff7fc2740 (LWP 8157))] (running)
>> +     (gdb)
>> +
>> +  As consequence, thread numbers as visible in the $_thread
>> +  convenience variable are no longer unique between inferiors.
> 
> I stumbled on the "as a convenience" part.  It took me a few seconds
> to understand that this refers to the "Thread numbers are now per
> inferior instead of global" part at the beginning, rather than to the
> later description of "qualified IDs".  So I suggest to say that
> explicitly:
> 
>   As a consequence of thread numbers being per inferior, the value of
>   the $_thread convenience variable are no longer unique between
>   inferiors.
> 
> Alternatively (maybe even better), move this sentence immediately
> after the first one.

OK, I reordered.

> 
>> +You can refer to a given thread in an inferior using the qualified
>> +@var{inferior-num}.@var{thread-num} syntax, with @var{inferior-num}
> 
> Suggest a @cindex entry here about "qualified thread ID".

Added.  Also added a @dfn while at it:

 You can refer to a given thread in an inferior using the qualified
 @var{inferior-num}.@var{thread-num} syntax, also known as
 @dfn{qualified thread ID}, with @var{inferior-num} being the inferior

Likewise for the global thread ID part.

> 
>> +                                If you omit @var{inferior-num}, then
>> +@value{GDBN} infers you're referring to a thread of the current
>> +inferior.
> 
> This begs a question: do you mean "thread .2" or "thread 2" here?
> IOW, what does "omit" stand for?

I added an example.

> 
>> +@kindex thread @var{thread-id}
>> +@item thread @var{thread-id}
>> +Make thread ID @var{thread-id} the current thread.  The command
>> +argument @var{thread-id} is the internal @value{GDBN} thread ID, as
>                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>  shown in the first field of the @samp{info threads} display.
> 
> Why not use "qualified thread ID" here?

This is not always inferior-qualified.  It depends on whether you
created a second inferior, as described earlier in the thread IDs
description:

 Until you create a second inferior, @value{GDBN} does not show the
 @var{inferior-num} part of thread IDs, even though you can always use
 the full @var{inferior-num}.@var{thread-num} form to refer to threads
 of inferior 1, the initial inferior.

Should I drop "internal", perhaps?  Currently (unpatched) it says:

-Make thread number @var{threadno} the current thread.  The command
-argument @var{threadno} is the internal @value{GDBN} thread number, as

In any case, I've added an example now:

+Make thread ID @var{thread-id} the current thread.  The command
+argument @var{thread-id} is the internal @value{GDBN} thread ID, as
+shown in the first field of the @samp{info threads} display, with or
+without an inferior qualifier (e.g., @samp{2.1} or @samp{1}).


> 
>> +The debugger convenience variable @samp{$_thread} contains the
>> +per-inferior thread number of the current thread.  You may find this
>> +useful in writing breakpoint conditional expressions, command scripts,
>> +and so forth.  @xref{Convenience Vars,, Convenience Variables}, for
>> +general information on convenience variables.
>> +
>> +@vindex $_gthread@r{, convenience variable}
>> +The debugger convenience variable @samp{$_gthread} contains the global
>> +number of the current thread, independent of the thread's containing
>> +inferior.  You may find this useful in writing breakpoint conditional
>> +expressions, command scripts, and so forth.  See @xref{Convenience
>> +Vars,, Convenience Variables}, for general information on convenience
>> +variables.
> 
> (There's "See @xref" again.)  You have here almost exactly the same
> text twice, complete with 2 identical cross-references to the same
> place.  I suggest to have the text only once, and describe both
> variables together, like this:
>  
>  The debugger convenience variables @samp{$_thread} and
>  samp{$_gthread} contain, respectively, the per-inferior thread number
>  and the global thread number of the current thread.  You may find ...

Thanks!  I used it.

> 
>> +@var{thread-id}.  It can be a single thread ID, as shown in the first
>> +field of the @samp{info threads} display, with or without an inferior
>> +qualifier (e.g., @samp{2.1} or @samp{1}); or it could be a range of
>> +thread numbers, as in @code{2-4}.  To apply a command to all threads
>> +in descending order, type @kbd{thread apply all @var{command}}.  To
>> +apply a command to all threads in ascending order, type @kbd{thread
>> +apply all -ascending @var{command}}.
> 
> Can I use a range of qualified IDs, as in "2.1-2.4"?

I was thinking of adding support for ranges of threads in the "2.1-4"
form, that is, I didn't think it'd make sense to cross inferior,
like "2.1-3.3", but I haven't implemented it yet.

> 
>> -Make @var{threadnum} the current thread.  It prints the number of the new
>> -current thread, and the topmost frame for that thread.
>> +Make thread with global thread num @var{threadnum} the current thread.
>                                   ^^^
> "num" is not a word.  Please use "number".
> 

Done.

Thank you very much for the review and suggestions thus far.
Here's an updated docs patch.  Let me know how it looks.

diff --git c/gdb/NEWS w/gdb/NEWS
index 484d98d..e4791cd 100644
--- c/gdb/NEWS
+++ w/gdb/NEWS
@@ -3,6 +3,46 @@
 
 *** Changes since GDB 7.10
 
+* Per-inferior thread numbers
+
+  Thread numbers are now per inferior instead of global.  If you're
+  debugging multiple inferiors, GDB displays thread IDs using a
+  qualified INF_NUM.THR_NUM form.  For example:
+
+     (gdb) info threads
+       Id   Target Id         Frame
+       1.1  Thread 0x7ffff7fc2740 (LWP 8155) (running)
+       1.2  Thread 0x7ffff7fc1700 (LWP 8168) (running)
+     * 2.1  Thread 0x7ffff7fc2740 (LWP 8157) (running)
+       2.2  Thread 0x7ffff7fc1700 (LWP 8190) (running)
+
+  As consequence, thread numbers as visible in the $_thread
+  convenience variable and in Python's InferiorThread.num attribute
+  are no longer unique between inferiors.
+
+  GDB now maintains a second thread ID per thread, referred to as the
+  global thread ID, which is the new equivalent of thread numbers in
+  previous releases.  See also $_gthread below.
+
+  For backwards compatibility, MI's thread IDs always refer to global
+  IDs.
+
+* Commands that accept thread IDs now accept the qualified
+  INF_NUM.THR_NUM form as well.  For example:
+
+     (gdb) thread 2.1
+     [Switching to thread 2.1 (Thread 0x7ffff7fc2740 (LWP 8157))] (running)
+     (gdb)
+
+* You can use "info threads -gid" to display the global thread ID of
+  all threads.
+
+* The new convenience variable $_gthread holds the global number of
+  the current thread.
+
+* The new convenience variable $_inferior holds the number of the
+  current inferior.
+
 * Record btrace now supports non-stop mode.
 
 * Support for tracepoints on aarch64-linux was added in GDBserver.
@@ -148,6 +188,15 @@ show remote exec-event-feature-packet
      format.  It outputs data in hexadecimal format with zero-padding on the
      left.
 
+* Python Scripting
+
+  ** gdb.InferiorThread objects have a new attribute "global_num",
+     which refers to the thread's global thread ID.  The existing
+     "num" attribute now refers to the thread's per-inferior number.
+     See "Per-inferior thread numbers" above.
+  ** gdb.InferiorThread objects have a new attribute "inferior", which
+     is the Inferior object the thread belongs to.
+
 *** Changes in GDB 7.10
 
 * Support for process record-replay and reverse debugging on aarch64*-linux*
diff --git c/gdb/doc/gdb.texinfo w/gdb/doc/gdb.texinfo
index 7cc1b35..d5a43fb 100644
--- c/gdb/doc/gdb.texinfo
+++ w/gdb/doc/gdb.texinfo
@@ -2658,6 +2658,12 @@ Make inferior number @var{infno} the current inferior.  The argument
 in the first field of the @samp{info inferiors} display.
 @end table
 
+@vindex $_inferior@r{, convenience variable}
+The debugger convenience variable @samp{$_inferior} contains the
+number of the current inferior.  You may find this useful in writing
+breakpoint conditional expressions, command scripts, and so forth.
+@xref{Convenience Vars,, Convenience Variables}, for general
+information on convenience variables.
 
 You can get multiple executables into a debugging session via the
 @code{add-inferior} and @w{@code{clone-inferior}} commands.  On some
@@ -2832,9 +2838,9 @@ programs:
 
 @itemize @bullet
 @item automatic notification of new threads
-@item @samp{thread @var{threadno}}, a command to switch among threads
+@item @samp{thread @var{thread-id}}, a command to switch among threads
 @item @samp{info threads}, a command to inquire about existing threads
-@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
+@item @samp{thread apply [@var{thread-id}] [@var{all}] @var{args}},
 a command to apply a command to a list of threads
 @item thread-specific breakpoints
 @item @samp{set print thread-events}, which controls printing of 
@@ -2880,15 +2886,49 @@ further qualifier.
 @c         multithread systems permit starting a program with multiple
 @c         threads ab initio?
 
-@cindex thread number
+@anchor{thread numbers}
+@cindex thread number, per inferior
 @cindex thread identifier (GDB)
-For debugging purposes, @value{GDBN} associates its own thread
-number---always a single integer---with each thread in your program.
+For debugging purposes, @value{GDBN} associates its own thread number
+---always a single integer---with each thread of an inferior.  This
+number is unique between all threads of an inferior, but not unique
+between threads of different inferiors.
+
+@cindex qualified thread ID
+You can refer to a given thread in an inferior using the qualified
+@var{inferior-num}.@var{thread-num} syntax, also known as
+@dfn{qualified thread ID}, with @var{inferior-num} being the inferior
+number and @var{thread-num} being the thread number of the given
+inferior.  For example, thread @code{2.3} refers to thread number 3 of
+inferior 2.  If you omit @var{inferior-num} (e.g., @code{thread 3}),
+then @value{GDBN} infers you're referring to a thread of the current
+inferior.
+
+Until you create a second inferior, @value{GDBN} does not show the
+@var{inferior-num} part of thread IDs, even though you can always use
+the full @var{inferior-num}.@var{thread-num} form to refer to threads
+of inferior 1, the initial inferior.
+
+@anchor{global thread numbers}
+@cindex global thread number
+@cindex global thread identifier (GDB)
+In addition to a @emph{per-inferior} number, each thread is also
+assigned a unique @emph{global} number, also known as @dfn{global
+thread ID}, a single integer.  Unlike the thread number component of
+the thread ID, no two threads have the same global ID, even when
+you're debugging multiple inferiors.
 
 From @value{GDBN}'s perspective, a process always has at least one
 thread.  In other words, @value{GDBN} assigns a thread number to the
 program's ``main thread'' even if the program is not multi-threaded.
 
+The debugger convenience variables @samp{$_thread} and
+@samp{$_gthread} contain, respectively, the per-inferior thread number
+and the global thread number of the current thread.  You may find this
+useful in writing breakpoint conditional expressions, command scripts,
+and so forth.  @xref{Convenience Vars,, Convenience Variables}, for
+general information on convenience variables.
+
 @table @code
 @kindex info threads
 @item info threads @r{[}@var{id}@dots{}@r{]}
@@ -2899,7 +2939,11 @@ means to print information only about the specified thread or threads.
 
 @enumerate
 @item
-the thread number assigned by @value{GDBN}
+the per-inferior thread number assigned by @value{GDBN}
+
+@item
+the global thread number assigned by @value{GDBN}, if the @samp{-gid}
+option was specified
 
 @item
 the target system's thread identifier (@var{systag})
@@ -2930,6 +2974,22 @@ For example,
     at threadtest.c:68
 @end smallexample
 
+If you're debugging multiple inferiors, @value{GDBN} displays thread
+IDs using the qualified @var{inferior-num}.@var{thread-num} format.
+Otherwise, only @var{thread-num} is shown.
+
+If you specify the @samp{-gid} option, @value{GDBN} displays a column
+indicating each thread's global thread ID:
+
+@smallexample
+(@value{GDBP}) info threads
+  Id   GId  Target Id             Frame
+  1.1  1    process 35 thread 13  main (argc=1, argv=0x7ffffff8)
+  1.2  3    process 35 thread 23  0x34e5 in sigpause ()
+  1.3  4    process 35 thread 27  0x34e5 in sigpause ()
+* 2.1  2    process 65 thread 1   main (argc=1, argv=0x7ffffff8)
+@end smallexample
+
 On Solaris, you can display more information about user threads with a
 Solaris-specific command:
 
@@ -2941,13 +3001,15 @@ Display info on Solaris user threads.
 @end table
 
 @table @code
-@kindex thread @var{threadno}
-@item thread @var{threadno}
-Make thread number @var{threadno} the current thread.  The command
-argument @var{threadno} is the internal @value{GDBN} thread number, as
-shown in the first field of the @samp{info threads} display.
-@value{GDBN} responds by displaying the system identifier of the thread
-you selected, and its current stack frame summary:
+@kindex thread @var{thread-id}
+@item thread @var{thread-id}
+Make thread ID @var{thread-id} the current thread.  The command
+argument @var{thread-id} is the internal @value{GDBN} thread ID, as
+shown in the first field of the @samp{info threads} display, with or
+without an inferior qualifier (e.g., @samp{2.1} or @samp{1}).
+
+@value{GDBN} responds by displaying the system identifier of the
+thread you selected, and its current stack frame summary:
 
 @smallexample
 (@value{GDBP}) thread 2
@@ -2961,25 +3023,19 @@ As with the @samp{[New @dots{}]} message, the form of the text after
 @samp{Switching to} depends on your system's conventions for identifying
 threads.
 
-@vindex $_thread@r{, convenience variable}
-The debugger convenience variable @samp{$_thread} contains the number
-of the current thread.  You may find this useful in writing breakpoint
-conditional expressions, command scripts, and so forth.  See
-@xref{Convenience Vars,, Convenience Variables}, for general
-information on convenience variables.
-
 @kindex thread apply
 @cindex apply command to several threads
-@item thread apply [@var{threadno} | all [-ascending]] @var{command}
+@item thread apply [@var{thread-id} | all [-ascending]] @var{command}
 The @code{thread apply} command allows you to apply the named
 @var{command} to one or more threads.  Specify the numbers of the
 threads that you want affected with the command argument
-@var{threadno}.  It can be a single thread number, one of the numbers
-shown in the first field of the @samp{info threads} display; or it
-could be a range of thread numbers, as in @code{2-4}.  To apply
-a command to all threads in descending order, type @kbd{thread apply all
-@var{command}}.  To apply a command to all threads in ascending order,
-type @kbd{thread apply all -ascending @var{command}}.
+@var{thread-id}.  It can be a single thread ID, as shown in the first
+field of the @samp{info threads} display, with or without an inferior
+qualifier (e.g., @samp{2.1} or @samp{1}); or it could be a range of
+thread numbers, as in @code{2-4}.  To apply a command to all threads
+in descending order, type @kbd{thread apply all @var{command}}.  To
+apply a command to all threads in ascending order, type @kbd{thread
+apply all -ascending @var{command}}.
 
 
 @kindex thread name
@@ -6045,25 +6101,25 @@ breakpoints on all threads, or on a particular thread.
 @table @code
 @cindex breakpoints and threads
 @cindex thread breakpoints
-@kindex break @dots{} thread @var{threadno}
-@item break @var{location} thread @var{threadno}
-@itemx break @var{location} thread @var{threadno} if @dots{}
+@kindex break @dots{} thread @var{thread-id}
+@item break @var{location} thread @var{thread-id}
+@itemx break @var{location} thread @var{thread-id} if @dots{}
 @var{location} specifies source lines; there are several ways of
 writing them (@pxref{Specify Location}), but the effect is always to
 specify some source line.
 
-Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
+Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command
 to specify that you only want @value{GDBN} to stop the program when a
-particular thread reaches this breakpoint.  The @var{threadno} specifier
-is one of the numeric thread identifiers assigned by @value{GDBN}, shown
+particular thread reaches this breakpoint.  The @var{thread-id} specifier
+is one of the thread identifiers assigned by @value{GDBN}, shown
 in the first column of the @samp{info threads} display.
 
-If you do not specify @samp{thread @var{threadno}} when you set a
+If you do not specify @samp{thread @var{thread-id}} when you set a
 breakpoint, the breakpoint applies to @emph{all} threads of your
 program.
 
 You can use the @code{thread} qualifier on conditional breakpoints as
-well; in this case, place @samp{thread @var{threadno}} before or
+well; in this case, place @samp{thread @var{thread-id}} before or
 after the breakpoint condition, like this:
 
 @smallexample
@@ -10382,6 +10438,16 @@ gdbserver that supports the @code{qGetTIBAddr} request.
 @xref{General Query Packets}.
 This variable contains the address of the thread information block.
 
+@item $_inferior
+The number of the current inferior.  @xref{Inferiors and
+Programs, ,Debugging Multiple Inferiors and Programs}.
+
+@item $_thread
+The thread number of the current thread.  @xref{thread numbers}.
+
+@item $_gthread
+The global number of the current thread.  @xref{global thread numbers}.
+
 @end table
 
 @node Convenience Funs
@@ -16124,7 +16190,7 @@ This command prints the ID of the current task.
 
 @item task @var{taskno}
 @cindex Ada task switching
-This command is like the @code{thread @var{threadno}}
+This command is like the @code{thread @var{thread-id}}
 command (@pxref{Threads}).  It switches the context of debugging
 from the current task to the given task.
 
@@ -25469,8 +25535,8 @@ increases the risk that by relying on implicitly selected thread, the
 frontend may be operating on a wrong one.  Therefore, each MI command
 should explicitly specify which thread and frame to operate on.  To
 make it possible, each MI command accepts the @samp{--thread} and
-@samp{--frame} options, the value to each is @value{GDBN} identifier
-for thread and frame to operate on.
+@samp{--frame} options, the value to each is @value{GDBN} global
+identifier for thread and frame to operate on.
 
 Usually, each top-level window in a frontend allows the user to select
 a thread and a frame, and remembers the user selection for further
@@ -26023,15 +26089,16 @@ The following is the list of possible async records:
 @table @code
 
 @item *running,thread-id="@var{thread}"
-The target is now running.  The @var{thread} field tells which
-specific thread is now running, and can be @samp{all} if all threads
-are running.  The frontend should assume that no interaction with a 
-running thread is possible after this notification is produced.
-The frontend should not assume that this notification is output
-only once for any command.  @value{GDBN} may emit this notification 
-several times, either for different threads, because it cannot resume
-all threads together, or even for a single thread, if the thread must
-be stepped though some code before letting it run freely.
+The target is now running.  The @var{thread} field can be the global
+thread ID of the the thread that is now running, and it can be
+@samp{all} if all threads are running.  The frontend should assume
+that no interaction with a running thread is possible after this
+notification is produced.  The frontend should not assume that this
+notification is output only once for any command.  @value{GDBN} may
+emit this notification several times, either for different threads,
+because it cannot resume all threads together, or even for a single
+thread, if the thread must be stepped though some code before letting
+it run freely.
 
 @item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}"
 The target has stopped.  The @var{reason} field can have one of the
@@ -26085,8 +26152,9 @@ The inferior called @code{exec}.  This is reported when @code{catch exec}
 (@pxref{Set Catchpoints}) has been used.
 @end table
 
-The @var{id} field identifies the thread that directly caused the stop
--- for example by hitting a breakpoint.  Depending on whether all-stop
+The @var{id} field identifies the global thread ID of the thread
+that directly caused the stop -- for example by hitting a breakpoint.
+Depending on whether all-stop
 mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either
 stop all threads, or only the thread that directly triggered the stop.
 If all threads are stopped, the @var{stopped} field will have the
@@ -26122,7 +26190,7 @@ only when the inferior exited with some code.
 @item =thread-created,id="@var{id}",group-id="@var{gid}"
 @itemx =thread-exited,id="@var{id}",group-id="@var{gid}"
 A thread either was created, or has exited.  The @var{id} field
-contains the @value{GDBN} identifier of the thread.  The @var{gid}
+contains the global @value{GDBN} identifier of the thread.  The @var{gid}
 field identifies the thread group this thread belongs to.
 
 @item =thread-selected,id="@var{id}"
@@ -26383,7 +26451,7 @@ uses a tuple with the following fields:
 
 @table @code
 @item id
-The numeric id assigned to the thread by @value{GDBN}.  This field is
+The global numeric id assigned to the thread by @value{GDBN}.  This field is
 always present.
 
 @item target-id
@@ -26856,7 +26924,8 @@ Make the breakpoint conditional on @var{condition}.
 @item -i @var{ignore-count}
 Initialize the @var{ignore-count}.
 @item -p @var{thread-id}
-Restrict the breakpoint to the specified @var{thread-id}.
+Restrict the breakpoint to the thread with the specified global
+@var{thread-id}.
 @end table
 
 @subsubheading Result
@@ -26946,7 +27015,8 @@ Make the breakpoint conditional on @var{condition}.
 Set the ignore count of the breakpoint (@pxref{Conditions, ignore count})
 to @var{ignore-count}.
 @item -p @var{thread-id}
-Restrict the breakpoint to the specified @var{thread-id}.
+Restrict the breakpoint to the thread with the specified global
+@var{thread-id}.
 @end table
 
 @subsubheading Result
@@ -27596,10 +27666,11 @@ The corresponding @value{GDBN} command is @samp{pwd}.
  -thread-info [ @var{thread-id} ]
 @end smallexample
 
-Reports information about either a specific thread, if 
-the @var{thread-id} parameter is present, or about all
-threads.  When printing information about all threads,
-also reports the current thread.
+Reports information about either a specific thread, if the
+@var{thread-id} parameter is present, or about all threads.
+@var{thread-id} is the thread's global thread ID.  When printing
+information about all threads, also reports the global ID of the
+current thread.
 
 @subsubheading @value{GDBN} Command
 
@@ -27616,7 +27687,7 @@ defined for a given thread:
 This field exists only for the current thread.  It has the value @samp{*}.
 
 @item id
-The identifier that @value{GDBN} uses to refer to the thread.
+The global identifier that @value{GDBN} uses to refer to the thread.
 
 @item target-id
 The identifier that the target uses to refer to the thread.
@@ -27682,8 +27753,9 @@ current-thread-id="1"
  -thread-list-ids
 @end smallexample
 
-Produces a list of the currently known @value{GDBN} thread ids.  At the
-end of the list it also prints the total number of such threads.
+Produces a list of the currently known global @value{GDBN} thread ids.
+At the end of the list it also prints the total number of such
+threads.
 
 This command is retained for historical reasons, the
 @code{-thread-info} command should be used instead.
@@ -27712,8 +27784,9 @@ current-thread-id="1",number-of-threads="3"
  -thread-select @var{threadnum}
 @end smallexample
 
-Make @var{threadnum} the current thread.  It prints the number of the new
-current thread, and the topmost frame for that thread.
+Make thread with global thread number @var{threadnum} the current
+thread.  It prints the number of the new current thread, and the
+topmost frame for that thread.
 
 This command is deprecated in favor of explicitly using the
 @samp{--thread} option to each command.
@@ -27782,7 +27855,8 @@ The identifier that @value{GDBN} uses to refer to the Ada task.
 The identifier that the target uses to refer to the Ada task.
 
 @item thread-id
-The identifier of the thread corresponding to the Ada task.
+The global thread identifier of the thread corresponding to the Ada
+task.
 
 This field should always exist, as Ada tasks are always implemented
 on top of a thread.  But if @value{GDBN} cannot find this corresponding
@@ -28998,7 +29072,7 @@ would be printed by the @value{GDBN} CLI.  If @samp{print object}
 
 @item thread-id
 If a variable object is bound to a specific thread, then this is the
-thread's identifier.
+thread's global identifier.
 
 @item has_more
 For a dynamic varobj, this indicates whether there appear to be any
@@ -29179,8 +29253,8 @@ The type of the child.  If @samp{print object}
 If values were requested, this is the value.
 
 @item thread-id
-If this variable object is associated with a thread, this is the thread id.  
-Otherwise this result is not present.
+If this variable object is associated with a thread, this is the
+thread's global thread id.  Otherwise this result is not present.
 
 @item frozen
 If the variable object is frozen, this variable will be present with a value of 1.