[python] [doc] PR 12930/12802 (clarify Breakpoint::stop doco)

Phil Muldoon
2011-10-06T10:59:19Z

This patch address the PRs 12930, and 12802 which both arise from
confusion regarding the scope of actions in the Breakpoint::stop
callback. I have added some documentation to clarify.

Pedro, please excuse the gratuitous CC, but beyond Eli's normal review
can you please fact-check the documentation to make sure I am not
writing something about states that is incorrect.

Cheers,

Phil

--

2011-10-06 Phil Muldoon <pmuldoon@redhat.com>

PR python/12930
PR python/12802

* gdb.texinfo (Breakpoints In Python): Clarify behavior in the
stop method.

--

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index dd0f7f6..0a66f5c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23552,6 +23552,18 @@ methods have a chance to execute at that location. In this scenario
if one of the methods returns @code{True} but the others return
@code{False}, the inferior will still be stopped.

+When @value{GDBN} executes each @code{stop} method, the inferior has
+been stopped, but the internal state accounting for that inferior is
+undetermined. As the return value from each @code{stop} method has the
+potential to instruct @value{GDBN} to restart the inferior, or keep it
+in a stopped state, this indeterminate state will remain until the
+execution scope of each @code{stop} method has been completed. Therefore
+you should not alter the execution state of the inferior (IE step, next,
+etc), alter the current frame context (IE change the current active
+frame), or alter, add or delete any breakpoint. As a general rule, you
+should not alter any data within @value{GDBN} or the inferior at this
+time.
+
Example @code{stop} implementation:

@smallexample