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

[Eli Zaretskii <eliz@gnu.org>]

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

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.