[doco/threads] document internal thread signals on gnu/linux

[doco/threads] document internal thread signals on gnu/linux

[Michael Elizabeth Chastain]

This patch adds some doco about the existence and side effects
of thread internal signals in GNU/Linux systems.

It should be, errr, self-documenting.  If you can't figure out
what I'm talking about, then I need to rewrite this.

I'm motivated to write this because one of our test programs actually
has a coding error in it, and this doco explains why the test program is
badly written and what happens when such a program is run under gdb.

I'm looking for two kinds of comments: (1) is the content okay,
and (2) is the formatting okay.

Michael C

2003-10-23  Michael Chastain  <mec@shout.net>

	* gdb.texinfo (Threads): Document the existence and side effects
	of thread internal signals in GNU/Linux systems.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.183
diff -c -3 -p -r1.183 gdb.texinfo
*** gdb.texinfo	23 Oct 2003 00:11:59 -0000	1.183
--- gdb.texinfo	24 Oct 2003 01:16:19 -0000
*************** signal happened.  @value{GDBN} alerts yo
*** 2257,2262 ****
--- 2257,2289 ----
  message of the form @samp{[Switching to @var{systag}]} to identify the
  thread.
  
+ @cindex signals, internal for threads
+ @cindex threads, internal signals
+ On @sc{gnu}/Linux systems, the thread library generates extra internal
+ signals when it detects that your program is running under @value{GDBN}.
+ This leads to an undesirable interaction: if some of the threads in your
+ program are blocked inside system calls, and your program performs
+ certain tasks such as creating a thread or destroying a thread, then the
+ system calls in other threads may return prematurely.
+ 
+ To handle this problem, your program should check the return value
+ of each system call and react appropriately.  This is good programming
+ style anyways.
+ 
+ For example, do not write code like this:
+ 
+ @smallexample
+   sleep (10);
+ @end smallexample
+ 
+ Instead, write this:
+ 
+ @smallexample
+   int unslept = 10;
+   while (unslept > 0)
+     unslept = sleep (unslept);
+ @end smallexample
+ 
  @xref{Thread Stops,,Stopping and starting multi-thread programs}, for
  more information about how @value{GDBN} behaves when you stop and start
  programs with multiple threads.

Re: [doco/threads] document internal thread signals on gnu/linux

[Daniel Jacobowitz]

On Thu, Oct 23, 2003 at 09:23:03PM -0400, Michael Elizabeth Chastain wrote:
> This patch adds some doco about the existence and side effects
> of thread internal signals in GNU/Linux systems.
> 
> It should be, errr, self-documenting.  If you can't figure out
> what I'm talking about, then I need to rewrite this.
> 
> I'm motivated to write this because one of our test programs actually
> has a coding error in it, and this doco explains why the test program is
> badly written and what happens when such a program is run under gdb.
> 
> I'm looking for two kinds of comments: (1) is the content okay,
> and (2) is the formatting okay.

Close, but not quite.

It's not extra signals that are the problem.  The thread library
(nowadays!) generates no more signals under GDB than otherwise, but it
does generate a lot of signals.  GDB knows how to ignore them.

However, at some events the thread library calls a function where GDB
puts a breakpoint.  This causes GDB to stop all threads.

Gdbserver does not suffer from this problem with such severity.  I hope
to free GDB from it eventually also, but the internals have a long way
to go first.

It can still happen if you stop the program for another reason, of
course, like a normal breakpoint.

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

Re: [doco/threads] document internal thread signals on gnu/linux

[Eli Zaretskii]

> Date: Thu, 23 Oct 2003 21:23:03 -0400
> From: Michael Elizabeth Chastain <mec@shout.net>
> 
> I'm looking for two kinds of comments: (1) is the content okay,
> and (2) is the formatting okay.

The Texinfo markup is okay, but it sounds like the text will need to
be rewritten.

Also, please think what index entries would you, as a user who bumped
into this problem, look for, and perhaps add more @cindex entries.
The hardest thing with this kind of factoids is not to bury them in
the manual where no reasonable user will ever find them.  Good
indexing can alleviate this problem.

Thanks.