This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[doc/internal manual] Describe the executing and running/stopped/exited thread properties
- From: Pedro Alves <pedro at codesourcery dot com>
- To: gdb-patches at sourceware dot org
- Date: Sun, 17 Aug 2008 01:02:46 +0100
- Subject: [doc/internal manual] Describe the executing and running/stopped/exited thread properties
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