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

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

[Michael Elizabeth Chastain]

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

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

[Eli Zaretskii]

> Date: Sun, 26 Oct 2003 09:59:25 -0500
> From: Michael Elizabeth Chastain <mec@shout.net>
> 
> Looking for approval from a thread guy such as Daniel J for content,
> and Eli Z for syntax.

Approved, with one gotcha: the GNU project standards discourage the
use of ``illegal'' for anything other than actions that break the law.
So I would rewrite the following sentence:

> + It is legal behavior for a system call to return early, so @value{GDBN}
> + does not cause your program to behave illegally.

like this:

  It is perfectly okay for a system call to return early, so @value{GDBN}
  does not cause your problem to behave erratically.

I would also suggest to add that the early return is due to a signal
(SIGTRAP, right?) caused by the breaking breakpoint.  This will help
programmers who know that a system call can return early due to a
signal to understand better what's going on.

Thanks.

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

[Daniel Jacobowitz]

On Sun, Oct 26, 2003 at 07:30:33PM +0200, Eli Zaretskii wrote:
> > Date: Sun, 26 Oct 2003 09:59:25 -0500
> > From: Michael Elizabeth Chastain <mec@shout.net>
> > 
> > Looking for approval from a thread guy such as Daniel J for content,
> > and Eli Z for syntax.

Also approved - pretty good!

> Approved, with one gotcha: the GNU project standards discourage the
> use of ``illegal'' for anything other than actions that break the law.
> So I would rewrite the following sentence:
> 
> > + It is legal behavior for a system call to return early, so @value{GDBN}
> > + does not cause your program to behave illegally.
> 
> like this:
> 
>   It is perfectly okay for a system call to return early, so @value{GDBN}
>   does not cause your problem to behave erratically.
> 
> I would also suggest to add that the early return is due to a signal
> (SIGTRAP, right?) caused by the breaking breakpoint.  This will help
> programmers who know that a system call can return early due to a
> signal to understand better what's going on.

Well, it's actually due to a SIGSTOP sent by GDB to the thread.  The
thread never receives the SIGSTOP (GDB cancels it later) but it causes
the system call to exit early.

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

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

[Andrew Cagney]

> + It is legal behavior for a system call to return early, so @value{GDBN}
>> + does not cause your program to behave illegally.

Just for the future, would erroneous be a useful word?

Andrew

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

[Eli Zaretskii]

> Date: Mon, 27 Oct 2003 11:12:35 -0500
> From: Andrew Cagney <ac131313@redhat.com>
> 
> > + It is legal behavior for a system call to return early, so @value{GDBN}
> >> + does not cause your program to behave illegally.
> 
> Just for the future, would erroneous be a useful word?

Something like that, yes.

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

[Michael Elizabeth Chastain]

Committed!

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.

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

[Daniel Jacobowitz]

On Mon, Oct 27, 2003 at 08:02:06AM +0200, Eli Zaretskii wrote:
> > Date: Sun, 26 Oct 2003 16:34:03 -0500
> > From: Michael Elizabeth Chastain <mec@shout.net>
> > 
> > Okay, how about this?
> 
> I'm happy now; please commit this.

Me too.  Thanks very much, Michael!

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

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

[Eli Zaretskii]

> Date: Sun, 26 Oct 2003 16:34:03 -0500
> From: Michael Elizabeth Chastain <mec@shout.net>
> 
> Okay, how about this?

I'm happy now; please commit this.

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

[Michael Elizabeth Chastain]

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