[Python - doc] gdb.post_event description

[Python - doc] gdb.post_event description

[Kevin Pouget]

On Mon, Oct 10, 2011 at 9:06 PM, tromey at redhat dot com
<sourceware-bugzilla@sourceware.org> wrote:
> http://sourceware.org/bugzilla/show_bug.cgi?id=12802
>> [...]
>> the documentation of gdb.post_event seems not very clear if you don't look at
>> what is done internally -- I didn't -- but I think it should be safe to do it
>> this way
>
> Can you suggest how to fix the docs?


according to my experimentations, gdb_do_one_event, which (indirectly)
triggers the processing of Python events posted with gdb.post_event,
is executed right after the prompt has been displayed (and new
charactered fed in), and nowhere else (as far as I could investigate).

Does it look right to you?

Here is the current sentence about when the event will be processed:
> This callable will be invoked at some later point, during gdb's event processing.

I guess it worth being updated


Thanks,

Kevin

Re: [Python - doc] gdb.post_event description

[Tom Tromey]

>>>>> "Kevin" == Kevin Pouget <kevin.pouget@gmail.com> writes:

Kevin> according to my experimentations, gdb_do_one_event, which (indirectly)
Kevin> triggers the processing of Python events posted with gdb.post_event,
Kevin> is executed right after the prompt has been displayed (and new
Kevin> charactered fed in), and nowhere else (as far as I could investigate).

Kevin> Does it look right to you?

Yeah, but I would not want to document this too precisely; it is good, I
think, to have some leeway so we can run the event queue at other times
if we find the need in the future.

Tom

Re: [Python - doc] gdb.post_event description

[Kevin Pouget]

On Fri, Oct 14, 2011 at 9:48 PM, Tom Tromey <tromey@redhat.com> wrote:
>>>>>> "Kevin" == Kevin Pouget <kevin.pouget@gmail.com> writes:
>
> Kevin> according to my experimentations, gdb_do_one_event, which (indirectly)
> Kevin> triggers the processing of Python events posted with gdb.post_event,
> Kevin> is executed right after the prompt has been displayed (and new
> Kevin> charactered fed in), and nowhere else (as far as I could investigate).
>
> Kevin> Does it look right to you?
>
> Yeah, but I would not want to document this too precisely; it is good, I
> think, to have some leeway so we can run the event queue at other times
> if we find the need in the future.

sure,

but I think that the notion of "event" is quite vague here, for
instance we've got Python events, which are totally unrelated to
"post_event" (as far as I understood); and internally there are
inferior events.
(Actually, with that knowledge, I expected 'post_event' events to be
processed more often).

So I think it's important to state when the callback will be
triggered, give the prompt as an example, and mentioned that more
event processing points might be added in the next releases

What do you think about it?

Thanks,

Kevin

Re: [Python - doc] gdb.post_event description

[Phil Muldoon]

Kevin Pouget <kevin.pouget@gmail.com> writes:

> On Fri, Oct 14, 2011 at 9:48 PM, Tom Tromey <tromey@redhat.com> wrote:
>>>>>>> "Kevin" == Kevin Pouget <kevin.pouget@gmail.com> writes:
>>
>> Kevin> according to my experimentations, gdb_do_one_event, which (indirectly)
>> Kevin> triggers the processing of Python events posted with gdb.post_event,
>> Kevin> is executed right after the prompt has been displayed (and new
>> Kevin> charactered fed in), and nowhere else (as far as I could investigate).
>>
>> Kevin> Does it look right to you?
>>
>> Yeah, but I would not want to document this too precisely; it is good, I
>> think, to have some leeway so we can run the event queue at other times
>> if we find the need in the future.
>
> sure,
>
> but I think that the notion of "event" is quite vague here, for
> instance we've got Python events, which are totally unrelated to
> "post_event" (as far as I understood); and internally there are
> inferior events.
> (Actually, with that knowledge, I expected 'post_event' events to be
> processed more often).
>
> So I think it's important to state when the callback will be
> triggered, give the prompt as an example, and mentioned that more
> event processing points might be added in the next releases
>
> What do you think about it?

Sorry I did not see this until now.  The problem is that events are
processed in GDB (I believe) at different times, in different parts of
the code, and more importantly are subject to change.  

So if we document "blah event will be processed after foo operation",
then there is an expectation is that it will also be so.  We have
exposed an internal mechanic of GDB and cast it in an API promise. We
cannot live-up to that expectation. Nor should we, imo, imply any
guarantee when the event will be processed other than it will.

Cheers,

Phil

Re: [Python - doc] gdb.post_event description

[Tom Tromey]

>>>>> "Kevin" == Kevin Pouget <kevin.pouget@gmail.com> writes:

Kevin> but I think that the notion of "event" is quite vague here, for
Kevin> instance we've got Python events, which are totally unrelated to
Kevin> "post_event" (as far as I understood); and internally there are
Kevin> inferior events.
Kevin> (Actually, with that knowledge, I expected 'post_event' events to be
Kevin> processed more often).

Kevin> So I think it's important to state when the callback will be
Kevin> triggered, give the prompt as an example, and mentioned that more
Kevin> event processing points might be added in the next releases

Kevin> What do you think about it?

Yeah, the choice of name for 'gdb.post_event' was unfortunate.
I think a change to the docs making it clear that post_event and the
event mechanism are unrelated would be good.

I wouldn't even mind if it mentioned the CLI or accepting input or
something, as long as it also mentioned that we may expand it to run
at other times as well in the future.

Tom