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

[Michael Elizabeth Chastain <mec@shout.net>]

How embarrassing, my first doco on this was all wrong.

How about this?

Tested with makeinfo for syntax.

Looking for approval from a thread guy such as Daniel J for content,
and Eli Z 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 14:53:09 -0000
*************** allows you to examine the overall state 
*** 3761,3766 ****
--- 3761,3804 ----
  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.
+ 
+ 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
+ 
+ It is legal behavior for a system call to return early, so @value{GDBN}
+ does not cause your program to behave illegally.  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