Re: [PATCH] Per-inferior thread IDs

Eli Zaretskii
2015-12-17T16:54:20Z

> 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:

> + (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.

> +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".

> + 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?

> +@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?

> +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 ...

> +@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"?

> -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".