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

[Doug Evans <dje at google dot 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/  ?