From 36d86913b56cf8925b15fd47c1daeb70a739e09a Mon Sep 17 00:00:00 2001 From: Michael Chastain Date: Mon, 27 Oct 2003 13:59:08 +0000 Subject: 2003-10-26 Michael Chastain * gdb.texinfo (Thread Stops): Document the issue with premature return from system calls in multi-threaded programs. --- gdb/doc/ChangeLog | 5 +++++ gdb/doc/gdb.texinfo | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) (limited to 'gdb/doc') diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 2e72df7..04bfa95 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,8 @@ +2003-10-26 Michael Chastain + + * gdb.texinfo (Thread Stops): Document the issue with + premature return from system calls in multi-threaded programs. + 2003-10-24 Andrew Cagney * annotate.texinfo: Fix "fortunatly"[sic]. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 83faf29..1567f66 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -3761,6 +3761,47 @@ allows you to examine the overall state of the program, including 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 -- cgit v1.1