Re: [PATCH] Add bp_location to Python interface

[Doug Evans <dje at google dot com>]

On Tue, Jan 10, 2012 at 6:50 AM, Kevin Pouget <kevin.pouget@gmail.com> wrote:
>>> +@defun BpLocation.is_valid ()
>>> +Returns @code{True} if the @code{gdb.BpLocation} object is valid,
>>> +@code{False} if not. ?A @code{gdb.BpLocation} object may be invalidated by
>>> +GDB at any moment for internal reasons. ?All other @code{gdb.BpLocation}
>>> +methods and attributes will throw an exception if the object is invalid.
>>
>> @value{GDBN} instead of "GDB".
>>
>> In any case, the last 2 sentences sound scary: I could interpret them
>> as meaning I cannot trust the locations at all. ?If that is indeed so,
>> what use are they?
>
> that's already discussed above, but I don't want you to be scared, so
> let me explain what I meant:
> it's not "at any moment", but rather "after any call to GDB's Python
> interface". We may want to say that it's only breakpoint or
> execution-related calls, but _I_ can't ensure that this is true, and
> it 'might' change in the future:
>
>> A @code{gdb.BpLocation} object may be invalidated during
>> any call to @{GDB}'s API for internal reasons (for instance, but not limited to,
>> breakpoint or execution-related mechanisms).
>
> (I'm not sure what's the right Python term here for 'mechanisms',
> reading/writing an attribute may trigger internal functions, so 'call'
> or 'function' seem not to suit very well)

Don't take this as a requirement, but this volatility isn't a property
of python's BpLocations,
Thus I'd rather see the general discussion of why breakpoint locations
are volatile, scary, whatever, elsewhere, and just have a link to that
documentation here.
I think that will help clear things up: In the breakpoints section of
the manual just state what breakpoint locations are, what their
properties are, etc.  Then in the above docs you don't have to worry
so much about scaryness or whatever: Whatever issues locations have,
users already need to be at least somewhat aware of them.

Another reason to do this is that when Guile scripting gets added, we
don't want to have to document these issues twice. :-)