[PATCH] [gdb/doc] There's always a thread

[PATCH] [gdb/doc] There's always a thread

[Pedro Alves]

This warning is a few years out of date -- there's always a thread
nowadays.

gdb/doc/ChangeLog:

	* gdb.texinfo (Threads): Replace warning with explanation/example
	about single-threaded programs.
---
 gdb/doc/gdb.texinfo | 25 +++++++------------------
 1 file changed, 7 insertions(+), 18 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index e8b419c..df3a313 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2844,24 +2844,6 @@ the user specify which @code{libthread_db} to use if the default choice
 isn't compatible with the program.
 @end itemize
 
-@quotation
-@emph{Warning:} These facilities are not yet available on every
-@value{GDBN} configuration where the operating system supports threads.
-If your @value{GDBN} does not support threads, these commands have no
-effect.  For example, a system without thread support shows no output
-from @samp{info threads}, and always rejects the @code{thread} command,
-like this:
-
-@smallexample
-(@value{GDBP}) info threads
-(@value{GDBP}) thread 1
-Thread ID 1 not known.  Use the "info threads" command to
-see the IDs of currently known threads.
-@end smallexample
-@c FIXME to implementors: how hard would it be to say "sorry, this GDB
-@c                        doesn't support threads"?
-@end quotation
-
 @cindex focus of debugging
 @cindex current thread
 The @value{GDBN} thread debugging facility allows you to observe all
@@ -2903,6 +2885,13 @@ further qualifier.
 For debugging purposes, @value{GDBN} associates its own thread
 number---always a single integer---with each thread in your program.
 
+From @value{GDBN}'s perspective, a process always has at least one
+thread.  In other words, on systems that require linking programs with
+a threading library to access threading features
+(e.g,. @code{libpthread}), even if the program does not link with said
+library, @value{GDBN} assigns a thread number to the program's main
+thread.
+
 @table @code
 @kindex info threads
 @item info threads @r{[}@var{id}@dots{}@r{]}
-- 
1.9.3

Re: [PATCH] [gdb/doc] There's always a thread

[Eli Zaretskii]

> From: Pedro Alves <palves@redhat.com>
> Date: Thu, 10 Dec 2015 14:14:59 +0000
> 
> This warning is a few years out of date -- there's always a thread
> nowadays.
> 
> gdb/doc/ChangeLog:
> 
> 	* gdb.texinfo (Threads): Replace warning with explanation/example
> 	about single-threaded programs.

This is OK, but your particular wording makes it sound like systems
that have no threading libraries at all are not covered by the
description.  How about not mentioning the threading library and the
rest of confusing details, and instead just talk about single-threaded
programs?

Thanks.

Re: [PATCH] [gdb/doc] There's always a thread

[Pedro Alves]

On 12/10/2015 04:37 PM, Eli Zaretskii wrote:
>> From: Pedro Alves <palves@redhat.com>
>> Date: Thu, 10 Dec 2015 14:14:59 +0000
>>
>> This warning is a few years out of date -- there's always a thread
>> nowadays.
>>
>> gdb/doc/ChangeLog:
>>
>> 	* gdb.texinfo (Threads): Replace warning with explanation/example
>> 	about single-threaded programs.
> 
> This is OK, but your particular wording makes it sound like systems
> that have no threading libraries at all are not covered by the
> description.  How about not mentioning the threading library and the
> rest of confusing details, and instead just talk about single-threaded
> programs?

Let's try again then.  I was trying to explain things to the
audience that might go

 "OK, but the "single" in single-threaded already
  implies there's one thread.  What about non-threaded programs?
  I mean, those that don't link with -lpthread, even?"

What about this version that follow along your suggestion, but
says "not multi-threaded" instead?

From 18e418498d3199d64d501d1ec92eabec85fb510d Mon Sep 17 00:00:00 2001
From: Pedro Alves <palves@redhat.com>
Date: Thu, 10 Dec 2015 12:54:50 +0000
Subject: [PATCH] [gdb/doc] There's always a thread

This warning is a few years out of date -- there's always a thread
nowadays.

gdb/doc/ChangeLog:

	* gdb.texinfo (Threads): Replace warning with explanation
	about single-threaded programs.
---
 gdb/doc/gdb.texinfo | 22 ++++------------------
 1 file changed, 4 insertions(+), 18 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index e8b419c..bb68e21 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2844,24 +2844,6 @@ the user specify which @code{libthread_db} to use if the default choice
 isn't compatible with the program.
 @end itemize
 
-@quotation
-@emph{Warning:} These facilities are not yet available on every
-@value{GDBN} configuration where the operating system supports threads.
-If your @value{GDBN} does not support threads, these commands have no
-effect.  For example, a system without thread support shows no output
-from @samp{info threads}, and always rejects the @code{thread} command,
-like this:
-
-@smallexample
-(@value{GDBP}) info threads
-(@value{GDBP}) thread 1
-Thread ID 1 not known.  Use the "info threads" command to
-see the IDs of currently known threads.
-@end smallexample
-@c FIXME to implementors: how hard would it be to say "sorry, this GDB
-@c                        doesn't support threads"?
-@end quotation
-
 @cindex focus of debugging
 @cindex current thread
 The @value{GDBN} thread debugging facility allows you to observe all
@@ -2903,6 +2885,10 @@ further qualifier.
 For debugging purposes, @value{GDBN} associates its own thread
 number---always a single integer---with each thread in your program.
 
+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.
+
 @table @code
 @kindex info threads
 @item info threads @r{[}@var{id}@dots{}@r{]}
-- 
1.9.3

Re: [PATCH] [gdb/doc] There's always a thread

[Eli Zaretskii]

> Date: Thu, 10 Dec 2015 17:10:11 +0000
> From: Pedro Alves <palves@redhat.com>
> CC: gdb-patches@sourceware.org
> 
> What about this version that follow along your suggestion, but
> says "not multi-threaded" instead?

It's perfect, thanks.

Re: [PATCH] [gdb/doc] There's always a thread

[Pedro Alves]

On 12/10/2015 05:38 PM, Eli Zaretskii wrote:
>> Date: Thu, 10 Dec 2015 17:10:11 +0000
>> From: Pedro Alves <palves@redhat.com>
>> CC: gdb-patches@sourceware.org
>>
>> What about this version that follow along your suggestion, but
>> says "not multi-threaded" instead?
> 
> It's perfect, thanks.

Pushed, thanks!

-- 
Pedro Alves