Per-inferior/Inferior-qualified thread IDs

This commit changes GDB to track thread numbers per-inferior.  Then,
if you're debugging multiple inferiors, GDB displays
"inferior-num.thread-num" instead of just "thread-num" whenever it
needs to display a thread:

 (gdb) info inferiors
   Num  Description       Executable
   1    process 6022     /home/pedro/gdb/tests/threads
 * 2    process 6037     /home/pedro/gdb/tests/threads
 (gdb) info threads
   Id   Target Id         Frame
   1.1  Thread 0x7ffff7fc2740 (LWP 6022) "threads" (running)
   1.2  Thread 0x7ffff77c0700 (LWP 6028) "threads" (running)
   1.3  Thread 0x7ffff7fc2740 (LWP 6032) "threads" (running)
   2.1  Thread 0x7ffff7fc1700 (LWP 6037) "threads" (running)
   2.2  Thread 0x7ffff77c0700 (LWP 6038) "threads" (running)
 * 2.3  Thread 0x7ffff7fc2740 (LWP 6039) "threads" (running)
 (gdb)
...
 (gdb) thread 1.1
 [Switching to thread 1.1 (Thread 0x7ffff7fc2740 (LWP 8155))]
 (gdb)
...

etc.

You can still use "thread NUM", in which case GDB infers you're
referring to thread NUM of the current inferior.

The $_thread convenience var and Python's InferiorThread.num attribute
are remapped to the new per-inferior thread number.  It's a backward
compatibility break, but since it only matters when debugging multiple
inferiors, I think it's worth doing.

Because MI thread IDs need to be a single integer, we keep giving
threads a global identifier, _in addition_ to the per-inferior number,
and make MI always refer to the global thread IDs.  IOW, nothing
changes from a MI frontend's perspective.

Similarly, since Python's Breakpoint.thread and Guile's
breakpoint-thread/set-breakpoint-thread breakpoint methods need to
work with integers, those are adjusted to work with global thread IDs
too.  Follow up patches will provide convenient means to access
threads' global IDs.

To avoid potencially confusing users (which also avoids updating much
of the testsuite), if there's only one inferior and its ID is "1",
IOW, the user hasn't done anything multi-process/inferior related,
then the "INF." part of thread IDs is not shown.  E.g,.:

 (gdb) info inferiors
   Num  Description       Executable
 * 1    process 15275     /home/pedro/gdb/tests/threads
 (gdb) info threads
   Id   Target Id         Frame
 * 1    Thread 0x7ffff7fc1740 (LWP 15275) "threads" main () at threads.c:40
 (gdb) add-inferior
 Added inferior 2
 (gdb) info threads
   Id   Target Id         Frame
 * 1.1  Thread 0x7ffff7fc1740 (LWP 15275) "threads" main () at threads.c:40
 (gdb)

No regressions on x86_64 Fedora 20.

gdb/ChangeLog:
2016-01-13  Pedro Alves  <palves@redhat.com>

	* NEWS: Mention that thread IDs are now per inferior and global
	thread IDs.
	* Makefile.in (SFILES): Add tid-parse.c.
	(COMMON_OBS): Add tid-parse.o.
	(HFILES_NO_SRCDIR): Add tid-parse.h.
	* ada-tasks.c: Adjust to use ptid_to_global_thread_id.
	* breakpoint.c (insert_breakpoint_locations)
	(remove_threaded_breakpoints, bpstat_check_breakpoint_conditions)
	(print_one_breakpoint_location, set_longjmp_breakpoint)
	(check_longjmp_breakpoint_for_call_dummy)
	(set_momentary_breakpoint): Adjust to use global IDs.
	(find_condition_and_thread, watch_command_1): Use parse_thread_id.
	(until_break_command, longjmp_bkpt_dtor)
	(breakpoint_re_set_thread, insert_single_step_breakpoint): Adjust
	to use global IDs.
	* dummy-frame.c (pop_dummy_frame_bpt): Adjust to use
	ptid_to_global_thread_id.
	* elfread.c (elf_gnu_ifunc_resolver_stop): Likewise.
	* gdbthread.h (struct thread_info): Rename field 'num' to
	'global_num.  Add new fields 'per_inf_num' and 'inf'.
	(thread_id_to_pid): Rename thread_id_to_pid to
	global_thread_id_to_ptid.
	(pid_to_thread_id): Rename to ...
	(ptid_to_global_thread_id): ... this.
	(valid_thread_id): Rename to ...
	(valid_global_thread_id): ... this.
	(find_thread_id): Rename to ...
	(find_thread_global_id): ... this.
	(ALL_THREADS, ALL_THREADS_BY_INFERIOR): Declare.
	(print_thread_info): Add comment.
	* tid-parse.h: New file.
	* tid-parse.c: New file.
	* infcmd.c (step_command_fsm_prepare)
	(step_command_fsm_should_stop): Adjust to use the global thread
	ID.
	(until_next_command, until_next_command)
	(finish_command_fsm_should_stop): Adjust to use the global thread
	ID.
	(attach_post_wait): Adjust to check the inferior number too.
	* inferior.h (struct inferior) <highest_thread_num>: New field.
	* infrun.c (handle_signal_stop)
	(insert_exception_resume_breakpoint)
	(insert_exception_resume_from_probe): Adjust to use the global
	thread ID.
	* record-btrace.c (record_btrace_open): Use global thread IDs.
	* remote.c (process_initial_stop_replies): Also consider the
	inferior number.
	* target.c (target_pre_inferior): Clear the inferior's highest
	thread num.
	* thread.c (clear_thread_inferior_resources): Adjust to use the
	global thread ID.
	(new_thread): New inferior parameter.  Adjust to use it.  Set both
	the thread's global ID and the thread's per-inferior ID.
	(add_thread_silent): Adjust.
	(find_thread_global_id): New.
	(find_thread_id): Make static.  Adjust to rename.
	(valid_thread_id): Rename to ...
	(valid_global_thread_id): ... this.
	(pid_to_thread_id): Rename to ...
	(ptid_to_global_thread_id): ... this.
	(thread_id_to_pid): Rename to ...
	(global_thread_id_to_ptid): ... this.  Adjust.
	(first_thread_of_process): Adjust.
	(do_captured_list_thread_ids): Adjust to use global thread IDs.
	(should_print_thread): New function.
	(print_thread_info): Rename to ...
	(print_thread_info_1): ... this, and add new show_global_ids
	parameter.  Handle it.  Iterate over inferiors.
	(print_thread_info): Reimplement as wrapper around
	print_thread_info_1.
	(show_inferior_qualified_tids): New function.
	(print_thread_id): Use it.
	(tp_array_compar): Compare inferior numbers too.
	(thread_apply_command): Use tid_range_parser.
	(do_captured_thread_select): Use parse_thread_id.
	(thread_id_make_value): Adjust.
	(_initialize_thread): Adjust "info threads" help string.
	* varobj.c (struct varobj_root): Update comment.
	(varobj_create): Adjust to use global thread IDs.
	(value_of_root_1): Adjust to use global_thread_id_to_ptid.
	* windows-tdep.c (display_tib): No longer accept an argument.
	* cli/cli-utils.c (get_number_trailer): Make extern.
	* cli/cli-utils.h (get_number_trailer): Declare.
	(get_number_const): Adjust documentation.
	* mi/mi-cmd-var.c (mi_cmd_var_update_iter): Adjust to use global
	thread IDs.
	* mi/mi-interp.c (mi_new_thread, mi_thread_exit)
	(mi_on_normal_stop, mi_output_running_pid, mi_on_resume):
	* mi/mi-main.c (mi_execute_command, mi_cmd_execute): Likewise.
	* guile/scm-breakpoint.c (gdbscm_set_breakpoint_thread_x):
	Likewise.
	* python/py-breakpoint.c (bppy_set_thread): Likewise.
	* python/py-finishbreakpoint.c (bpfinishpy_init): Likewise.
	* python/py-infthread.c (thpy_get_num): Add comment and return the
	per-inferior thread ID.
	(thread_object_getset): Update comment of "num".

gdb/testsuite/ChangeLog:
2016-01-07  Pedro Alves  <palves@redhat.com>

	* gdb.base/break.exp: Adjust to output changes.
	* gdb.base/hbreak2.exp: Likewise.
	* gdb.base/sepdebug.exp: Likewise.
	* gdb.base/watch_thread_num.exp: Likewise.
	* gdb.linespec/keywords.exp: Likewise.
	* gdb.multi/info-threads.exp: Likewise.
	* gdb.threads/thread-find.exp: Likewise.
	* gdb.multi/tids.c: New file.
	* gdb.multi/tids.exp: New file.

gdb/doc/ChangeLog:
2016-01-07  Pedro Alves  <palves@redhat.com>

	* gdb.texinfo (Threads): Document per-inferior thread IDs,
	qualified thread IDs, global thread IDs and thread ID lists.
	(Set Watchpoints, Thread-Specific Breakpoints): Adjust to refer to
	thread IDs.
	(Convenience Vars): Document the $_thread convenience variable.
	(Ada Tasks): Adjust to refer to thread IDs.
	(GDB/MI Async Records, GDB/MI Thread Commands, GDB/MI Ada Tasking
	Commands, GDB/MI Variable Objects): Update to mention global
	thread IDs.
	* guile.texi (Breakpoints In Guile)
	<breakpoint-thread/set-breakpoint-thread breakpoint>: Mention
	global thread IDs instead of thread IDs.
	* python.texi (Threads In Python): Adjust documentation of
	InferiorThread.num.
	(Breakpoint.thread): Mention global thread IDs instead of thread
	IDs.

4 files changed, 173 insertions, 85 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index be16225..46207f6 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,22 @@
+2016-01-07  Pedro Alves  <palves@redhat.com>
+
+	* gdb.texinfo (Threads): Document per-inferior thread IDs,
+	qualified thread IDs, global thread IDs and thread ID lists.
+	(Set Watchpoints, Thread-Specific Breakpoints): Adjust to refer to
+	thread IDs.
+	(Convenience Vars): Document the $_thread convenience variable.
+	(Ada Tasks): Adjust to refer to thread IDs.
+	(GDB/MI Async Records, GDB/MI Thread Commands, GDB/MI Ada Tasking
+	Commands, GDB/MI Variable Objects): Update to mention global
+	thread IDs.
+	* guile.texi (Breakpoints In Guile)
+	<breakpoint-thread/set-breakpoint-thread breakpoint>: Mention
+	global thread IDs instead of thread IDs.
+	* python.texi (Threads In Python): Adjust documentation of
+	InferiorThread.num.
+	(Breakpoint.thread): Mention global thread IDs instead of thread
+	IDs.
+
 2016-01-13  Pedro Alves  <palves@redhat.com>
 
 	* python.texi (Threads In Python): Document
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d4452a9..786556e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2838,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-list}] [@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 
@@ -2886,26 +2886,77 @@ 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{thread ID lists}
+@cindex thread ID lists
+Some commands accept a space-separated @dfn{thread ID list} as
+argument.  A list element can be a 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 can be a range of thread
+numbers, again with or without an inferior qualifier, as in
+@var{inf1}.@var{thr1}-@var{thr2} or @var{thr1}-@var{thr2} (e.g.,
+@samp{1.2-4} or @samp{2-4}).  For example, if the current inferior is
+1, the thread list @samp{1 2-3 4.5 6.7-9} includes threads 1 to 3 of
+inferior 1, thread 5 of inferior 4 and threads 7 to 9 of inferior 6.
+That is, in expanded qualified form, the same as @samp{1.1 1.2 1.3 4.5
+6.7 6.8 6.9}.
+
+@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.
 
+@vindex $_thread@r{, convenience variable}
+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.
+
 @table @code
 @kindex info threads
-@item info threads @r{[}@var{id}@dots{}@r{]}
-Display a summary of all threads currently in your program.  Optional 
-argument @var{id}@dots{} is one or more thread ids separated by spaces, and
-means to print information only about the specified thread or threads.
+@item info threads @r{[}@var{thread-id-list}@r{]}
+
+Display information about one or more threads.  With no arguments
+displays information about all threads.  You can specify the list of
+threads that you want to display using the thread ID list syntax
+(@pxref{thread ID lists}).
+
 @value{GDBN} displays for each thread (in this order):
 
 @enumerate
 @item
-the thread number assigned by @value{GDBN}
+the per-inferior thread number assigned by @value{GDBN}
 
 @item
 the target system's thread identifier (@var{systag})
@@ -2936,6 +2987,19 @@ 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:
+
+@smallexample
+(@value{GDBP}) info threads
+  Id   Target Id             Frame
+  1.1  process 35 thread 13  main (argc=1, argv=0x7ffffff8)
+  1.2  process 35 thread 23  0x34e5 in sigpause ()
+  1.3  process 35 thread 27  0x34e5 in sigpause ()
+* 2.1  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:
 
@@ -2947,13 +3011,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 @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
@@ -2967,23 +3033,14 @@ 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-list} | 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 one or more threads.  Specify the threads that you
+want affected using the thread ID list syntax (@pxref{thread ID
+lists}), or specify @code{all} to apply to all threads.  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}}.
 
@@ -3983,7 +4040,7 @@ slow down the running of your program.
 
 @table @code
 @kindex watch
-@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
 Set a watchpoint for an expression.  @value{GDBN} will break when the
 expression @var{expr} is written into by the program and its value
 changes.  The simplest (and the most popular) use of this command is
@@ -3993,9 +4050,9 @@ to watch the value of a single variable:
 (@value{GDBP}) watch foo
 @end smallexample
 
-If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
+If the command includes a @code{@r{[}thread @var{thread-id}@r{]}}
 argument, @value{GDBN} breaks only when the thread identified by
-@var{threadnum} changes the value of @var{expr}.  If any other threads
+@var{thread-id} changes the value of @var{expr}.  If any other threads
 change the value of @var{expr}, @value{GDBN} will not break.  Note
 that watchpoints restricted to a single thread in this way only work
 with Hardware Watchpoints.
@@ -4027,12 +4084,12 @@ Examples:
 @end smallexample
 
 @kindex rwatch
-@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
 Set a watchpoint that will break when the value of @var{expr} is read
 by the program.
 
 @kindex awatch
-@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
+@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]}
 Set a watchpoint that will break when @var{expr} is either read from
 or written into by the program.
 
@@ -6051,25 +6108,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
@@ -10392,6 +10449,9 @@ This variable contains the address of the thread information block.
 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}.
+
 @end table
 
 @node Convenience Funs
@@ -16134,7 +16194,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.
 
@@ -25483,8 +25543,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
@@ -26037,15 +26097,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
@@ -26099,8 +26160,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
@@ -26136,7 +26198,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}"
@@ -26397,7 +26459,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
@@ -26870,7 +26932,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
@@ -26960,7 +27023,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
@@ -27610,10 +27674,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
 
@@ -27630,7 +27695,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.
@@ -27696,8 +27761,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.
@@ -27723,11 +27789,12 @@ current-thread-id="1",number-of-threads="3"
 @subsubheading Synopsis
 
 @smallexample
- -thread-select @var{threadnum}
+ -thread-select @var{thread-id}
 @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{thread-id} 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.
@@ -27796,7 +27863,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
@@ -29012,7 +29080,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
@@ -29193,8 +29261,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.
diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index fa1ad53..840defc 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -3127,13 +3127,14 @@ At present, @var{count} must be zero.
 @end deffn
 
 @deffn {Scheme Procedure} breakpoint-thread breakpoint
-Return the thread-id for thread-specific breakpoint @var{breakpoint}.
-Return #f if @var{breakpoint} is not thread-specific.
+Return the global-thread-id for thread-specific breakpoint
+@var{breakpoint}.  Return #f if @var{breakpoint} is not
+thread-specific.
 @end deffn
 
-@deffn {Scheme Procedure} set-breakpoint-thread! breakpoint thread-id|#f
-Set the thread-id for @var{breakpoint} to @var{thread-id}.
-If set to @code{#f}, the breakpoint is no longer thread-specific.
+@deffn {Scheme Procedure} set-breakpoint-thread! breakpoint global-thread-id|#f
+Set the thread-id for @var{breakpoint} to @var{global-thread-id} If
+set to @code{#f}, the breakpoint is no longer thread-specific.
 @end deffn
 
 @deffn {Scheme Procedure} breakpoint-task breakpoint
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 855da44..f9f9e5b 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -2995,7 +2995,7 @@ user-specified thread name.
 @end defvar
 
 @defvar InferiorThread.num
-ID of the thread, as assigned by GDB.
+The per-inferior number of the thread, as assigned by GDB.
 @end defvar
 
 @defvar InferiorThread.ptid
@@ -4643,9 +4643,9 @@ first command is @code{silent}.  This is not reported by the
 @end defvar
 
 @defvar Breakpoint.thread
-If the breakpoint is thread-specific, this attribute holds the thread
-id.  If the breakpoint is not thread-specific, this attribute is
-@code{None}.  This attribute is writable.
+If the breakpoint is thread-specific, this attribute holds the
+thread's global id.  If the breakpoint is not thread-specific, this
+attribute is @code{None}.  This attribute is writable.
 @end defvar
 
 @defvar Breakpoint.task