Re: [RFC - doc] Add note about the possibility of symbols getting moved across blocks

[Doug Evans <dje@google.com>]

On Fri, Apr 27, 2012 at 8:36 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Fri, 27 Apr 2012 16:33:06 +0530
>> From: Siva Chandra <sivachandra@google.com>
>> Cc: Tom Tromey <tromey@redhat.com>, Doug Evans <dje@google.com>, gdb-patches@sourceware.org
>>
>> On Thu, Apr 26, 2012 at 7:43 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> > Maybe I simply miss something important here.  The text in question
>> > says this:
>> >
>> >   A @code{gdb.Block} is iterable.  The iterator returns the symbols
>> >   (@pxref{Symbols In Python}) local to the block.  Users using this
>> >   feature should keep in mind that future improvements to the internal
>> >   representation, of symbols and symbol tables, can move symbols across
>> >   blocks within a symbol table.
>> >
>> > Are you saying that future changes will prevent the possibility to
>> > get the symbols local to the block by iterating it?  That's not what
>> > the last sentence above seems to say.  It says that the symbols might
>> > be found in a different block, or something to that effect.  At least
>> > that's what I understand from reading it.  If my understanding is
>> > correct, how would my Python program that works today break with
>> > future versions of GDB?
>>
>> This is my thought:  Take Tom's example of current 'globals' ending up
>> in a namespace block due to a future change.  Now, this is just an
>> example.  Meaning, a future existence of a namespace block is a
>> speculation now.  Since it is a speculation, it could eventually so
>> happen that we will not have a namespace block but something else or
>> nothing at all.  Hence, how things would change are unknown now, but
>> there is a chance that things will change.  What Doug and Tom are
>> trying to say is that, "It is OK to use the API now and for some time
>> in future, but keep an eye out for changes and change accordingly."
>> Also, since how things would change in future is unknown now, it is
>> probably not possible to specify now as to how exactly would a Python
>> program break in future.

Thanks Siva.

> OK, thanks.  Then how about the following text?
>
>  A @code{gdb.Block} is iterable.  The iterator returns the symbols
>  (@pxref{Symbols In Python}) local to the block.  Python programs
>  should not assume that a specific block object will always contain a
>  given symbol, since changes in @value{GDBN} features and
>  infrastructure may cause symbols move across blocks in a symbol
>  table.

I think that's close enough.

s/symbols move/symbols to move/  ?