From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 103271 invoked by alias); 17 Dec 2015 16:54:20 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 103254 invoked by uid 89); 17 Dec 2015 16:54:19 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.2 required=5.0 tests=AWL,BAYES_00,SPF_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy=HX-Received-From:4830, HX-Received-From:134, HX-Received-From:2001, HX-HELO:eggs.gnu.org X-HELO: eggs.gnu.org Received: from eggs.gnu.org (HELO eggs.gnu.org) (208.118.235.92) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Thu, 17 Dec 2015 16:54:18 +0000 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9boh-0008JU-2H for gdb-patches@sourceware.org; Thu, 17 Dec 2015 11:54:15 -0500 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:34340) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9bog-0008JI-Vz; Thu, 17 Dec 2015 11:54:11 -0500 Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1427 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1a9bog-0003Cv-6t; Thu, 17 Dec 2015 11:54:10 -0500 Date: Thu, 17 Dec 2015 16:54:00 -0000 Message-Id: <83a8p9yq0p.fsf@gnu.org> From: Eli Zaretskii To: Pedro Alves CC: gdb-patches@sourceware.org In-reply-to: <5672B5D0.6020806@redhat.com> (message from Pedro Alves on Thu, 17 Dec 2015 13:17:04 +0000) Subject: Re: [PATCH] Per-inferior thread IDs Reply-to: Eli Zaretskii References: <1450206316-25680-1-git-send-email-palves@redhat.com> <8337v333id.fsf@gnu.org> <5672B5D0.6020806@redhat.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-IsSubscribed: yes X-SW-Source: 2015-12/txt/msg00342.txt.bz2 > Date: Thu, 17 Dec 2015 13:17:04 +0000 > From: Pedro Alves > CC: gdb-patches@sourceware.org > > On 12/15/2015 07:39 PM, Eli Zaretskii wrote: > >> From: Pedro Alves > >> 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".