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

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

[Phil Muldoon]

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

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

[Pedro Alves]

On Thursday 06 October 2011 11:58:51, Phil Muldoon wrote:
> 
> 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.

Thanks!  Looks good fact-wise.  I think infcalls will make sense to call here
(we do support them in the normal breakpoint condition), but that
supposedly doesn't leave the inferior's state unaltered, so we're good.

I could be made possible to self delete a breakpoint in the callback,
but that's not the current state of affairs, it seems.

-- 
Pedro Alves

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

[Phil Muldoon]

Pedro Alves <pedro@codesourcery.com> writes:

> On Thursday 06 October 2011 11:58:51, Phil Muldoon wrote:
>> 
>> 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.
>
> Thanks!  Looks good fact-wise.  I think infcalls will make sense to call here
> (we do support them in the normal breakpoint condition), but that
> supposedly doesn't leave the inferior's state unaltered, so we're good.
>
> I could be made possible to self delete a breakpoint in the callback,
> but that's not the current state of affairs, it seems.

I'm not opposed to allowing the user to delete, but my view is that
"stop" should make decisions, and not alter state.  OTOH, I'm not
strongly moved other than personal preferences, so I can remove that
line if need be.

Cheers,

Phil

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

[Pedro Alves]

On Thursday 06 October 2011 14:58:27, Phil Muldoon wrote:
> Pedro Alves <pedro@codesourcery.com> writes:
> 
> > On Thursday 06 October 2011 11:58:51, Phil Muldoon wrote:
> >> 
> >> 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.
> >
> > Thanks!  Looks good fact-wise.  I think infcalls will make sense to call here
> > (we do support them in the normal breakpoint condition), but that
> > supposedly doesn't leave the inferior's state unaltered, so we're good.
> >
> > I could be made possible to self delete a breakpoint in the callback,
> > but that's not the current state of affairs, it seems.
> 
> I'm not opposed to allowing the user to delete, but my view is that
> "stop" should make decisions, and not alter state.  OTOH, I'm not
> strongly moved other than personal preferences, so I can remove that
> line if need be.

Oh I didn't mean for you to remove it.  We can't do that currently,
so let's leave it in.  I was thinking that we do have internal
breakpoints that self-delete on some occasions, and it may be
useful to do the same from python --- e.g., local watchpoints going
out of scope, and the scope breakpoint.

-- 
Pedro Alves

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

[Eli Zaretskii]

> From: Phil Muldoon <pmuldoon@redhat.com>
> CC: eli@gnu.org, pedro@codesourcery.com
> Date: Thu, 06 Oct 2011 11:58:51 +0100
> 
> 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.

Thanks.

> +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.

Do we really need this part?  I feel it doesn't explain anything that
is instrumental for the rest of this paragraph, and it sounds
mysterious enough to puzzle and confuse.  How about dropping it and
just leaving the rest (minus the "Therefore" part)?

>                                                                Therefore
> +you should not alter the execution state of the inferior (IE step, next,
                                                             ^^
"i.e.@:", in lower case and with periods.

> +etc), alter the current frame context (IE change the current active

"etc.", with a period.

Okay with those changes.

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

[Phil Muldoon]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Phil Muldoon <pmuldoon@redhat.com>
>> CC: eli@gnu.org, pedro@codesourcery.com
>> Date: Thu, 06 Oct 2011 11:58:51 +0100
>> 
>> 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.
>
> Thanks.
>
>> +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.
>
> Do we really need this part?  I feel it doesn't explain anything that
> is instrumental for the rest of this paragraph, and it sounds
> mysterious enough to puzzle and confuse.  How about dropping it and
> just leaving the rest (minus the "Therefore" part)?

Yeah that is fine, I was just trying to justify why one should not
tinker with these areas during that time.  But that's something we
should have not have in the manual, in retrospect.  Thanks for the
review, I will make the changes and check it in.

Cheers

Phil

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

[Phil Muldoon]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Phil Muldoon <pmuldoon@redhat.com>
>> CC: eli@gnu.org, pedro@codesourcery.com
>> Date: Thu, 06 Oct 2011 11:58:51 +0100
>> 
>> 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.
>
> Thanks.
>
> Okay with those changes.

Thanks, so committed.

Cheers,

Phil