[doc/internal manual] Describe the executing and running/stopped/exited thread properties

[Pedro Alves <pedro at codesourcery dot com>]

Ok,

As promised, here is a gdb internals manual blurb trying to explain the
current possible thread states.

-- 
Pedro Alves

2008-08-17  Pedro Alves  <pedro@codesourcery.com>

	* gdb.texinfo (Thread states): New subsection.

---
 gdb/doc/gdbint.texinfo |   79 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

Index: src/gdb/doc/gdbint.texinfo
===================================================================
--- src.orig/gdb/doc/gdbint.texinfo	2008-08-17 00:48:09.000000000 +0100
+++ src/gdb/doc/gdbint.texinfo	2008-08-17 00:55:07.000000000 +0100
@@ -558,6 +558,85 @@ but @code{placed_size} may be.
 
 @section Thread Handling
 
+@subsection Thread states
+
+@value{GDBN} maintains two different states, in the @code{struct
+thread_info} object representing each thread of the inferior.
+
+@table @code
+@item executing state
+This is the internal view of the executing state of the thread.
+
+Internally, @value{GDBN} keeps an ``executing'' property attached to
+each thread.  As soon as the core knows a thread has stopped, the
+executing property is set to false.  This property is used by the
+frame and stack components to know if they can read registers and
+memory from the thread or not.  Whenever the a thread is resumed, this
+property is set to true.
+
+To check if a thread is known to be executing, use the
+@code{is_executing} function.  The thread executing state is changed
+with the @code{set_running} function, which takes a boolean argument
+representing the executing state to set the thread to.
+
+@item frontend or user visible state
+The represents the user or frontend view of the state of the thread.
+
+This state can be one of the following:
+
+@table @code
+@item running
+In the perpective of the frontend/user, this thread is running.
+
+It can happen that the thread stops momentarily, but the running state
+is not updated.  E.g., while doing a step operation, the thread will
+be stopped and resumed several times, once per each instruction
+single-stepped.  In this example, the frontend view of the state of
+the thread is only changed to stopped when the stepping range end is
+reached.
+
+It is valid for a thread to be tagged simultaneously as @code{running}
+and not @code{executing}.
+
+This state is used by the execution commands to refuse resuming a
+thread that is already running.  Note that it is the running property,
+not the executing property that is checked.  It can't be the latter
+property that is checked, because otherwise there would be situations
+where the user would be able to try to resume a thread that happened
+to not be executing momentarily, but was already performing another
+execution command.  E.g., a thread may be waiting for its turn in the
+displaced stepping queue, to continue an already progressing ``next''
+command.  See the @file{infrun.c}.
+
+To check if a thread is in this state, use the @code{is_stopped}
+function.  To set a thread to the @code{running} state, use the
+@code{set_running} function, passing true as argument.
+
+@item stopped
+In the perpective of the frontend/user, this thread is stopped.  The
+thread is tagged as stopped when @value{GDBN} decides that the user should be
+informed of the stop.  E.g., a breakpoint was hit, or a ``next''
+operation completed.
+
+To check if a thread is in this state, use the @code{is_stopped}
+function.  To set a thread to the @code{stopped} state, use the
+@code{set_running} function, passing false as argument.
+
+@item exited
+When the currently selected thread exits, @value{GDBN} will tag it as
+``exited'', but still keep it in the internal thread list.  Most
+commands are refused until the user selects a live thread.
+
+To check if a thread is in this state, use the @code{is_exited}
+function.
+
+A thread is set to the @code{exited} state, when the thread passed as
+argument to the @code{delete_thread} function is the currently
+selected thread.
+
+@end table
+@end table
+
 @section Inferior Function Calls
 
 @section Longjmp Support