Re: [rfa/doc/threads] thread breakpoints and system calls

[Michael Elizabeth Chastain <mec at shout dot net>]

Okay, how about this?

This version eschews the words 'legal' and 'illegal'.  It also adds a
sentence about the root cause, which is the interaction between
multiple threads and the signals used to implement breakpoints and
other events that stop execution.

Tested with makeinfo for syntax.

Michael C

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

	* gdb.texinfo (Thread Stops): Document the issue with
	premature return from system calls in multi-threaded programs.

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	26 Oct 2003 21:28:00 -0000
*************** allows you to examine the overall state 
*** 3761,3766 ****
--- 3761,3807 ----
  switching between threads, without worrying that things may change
  underfoot.
  
+ @cindex thread breakpoints and system calls
+ @cindex system calls and thread breakpoints
+ @cindex premature return from system calls
+ There is an unfortunate side effect.  If one thread stops for a
+ breakpoint, or for some other reason, and another thread is blocked in a
+ system call, then the system call may return prematurely.  This is a
+ consequence of the interaction between multiple threads and the signals
+ that @value{GDBN} uses to implement breakpoints and other events that
+ stop execution.
+ 
+ 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
+ 
+ The call to @code{sleep} will return early if a different thread stops
+ at a breakpoint or for some other reason.
+ 
+ Instead, write this:
+ 
+ @smallexample
+   int unslept = 10;
+   while (unslept > 0)
+     unslept = sleep (unslept);
+ @end smallexample
+ 
+ A system call is allowed to return early, so the system is still
+ conforming to its specification.  But @value{GDBN} does cause your
+ multi-threaded program to behave differently than it would without
+ @value{GDBN}.
+ 
+ Also, @value{GDBN} uses internal breakpoints in the thread library to
+ monitor certain events such as thread creation and thread destruction.
+ When such an event happens, a system call in another thread may return
+ prematurely, even though your program does not appear to stop.
+ 
  @cindex continuing threads
  @cindex threads, continuing
  Conversely, whenever you restart the program, @emph{all} threads start