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

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

[Siva Chandra]

[-- Attachment #1: Type: text/plain, Size: 396 bytes --]

Hello,

This patch is in response to the discussion here:
http://sourceware.org/ml/gdb-patches/2012-04/msg00845.html

2012-04-25  Siva Chandra Reddy  <sivachandra@google.com>

        * gdb.texinfo (Blocks In Python): Add a note saying that future
        improvements to symbol and symbol table representations can move
        symbols across blocks within a symbol table.

Thanks,
Siva Chandra

[-- Attachment #2: blocks_doc_patch_v1.txt --]
[-- Type: text/plain, Size: 794 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.948
diff -u -p -r1.948 gdb.texinfo
--- gdb.texinfo	23 Apr 2012 17:26:01 -0000	1.948
+++ gdb.texinfo	25 Apr 2012 07:53:58 -0000
@@ -24530,7 +24530,10 @@ detailed technical information on @value
 stack.
 
 A @code{gdb.Block} is iterable.  The iterator returns the symbols
-(@pxref{Symbols In Python}) local to the block.
+(@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.
 
 The following block-related functions are available in the @code{gdb}
 module:

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

[Eli Zaretskii]

> Date: Wed, 25 Apr 2012 13:36:20 +0530
> From: Siva Chandra <sivachandra@google.com>
> 
>  A @code{gdb.Block} is iterable.  The iterator returns the symbols
> -(@pxref{Symbols In Python}) local to the block.
> +(@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.

Thanks.  But I still don't see how the warning is useful.  What should
I do or not do if I want to avoid whatever dangers you warn me about?

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

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Wed, 25 Apr 2012 13:36:20 +0530
>> From: Siva Chandra <sivachandra@google.com>
>> 
>> A @code{gdb.Block} is iterable.  The iterator returns the symbols
>> -(@pxref{Symbols In Python}) local to the block.
>> +(@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.

Eli> Thanks.  But I still don't see how the warning is useful.  What should
Eli> I do or not do if I want to avoid whatever dangers you warn me about?

You could test new versions of gdb to be sure they conform to your
expectations.

Tom

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

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Cc: Siva Chandra <sivachandra@google.com>, gdb-patches@sourceware.org
> Date: Wed, 25 Apr 2012 13:45:15 -0600
> 
> >> A @code{gdb.Block} is iterable.  The iterator returns the symbols
> >> -(@pxref{Symbols In Python}) local to the block.
> >> +(@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.
> 
> Eli> Thanks.  But I still don't see how the warning is useful.  What should
> Eli> I do or not do if I want to avoid whatever dangers you warn me about?
> 
> You could test new versions of gdb to be sure they conform to your
> expectations.

I meant what should I do or not do as the user of the Python API in
question.

Or maybe I misunderstand what you are saying, sorry.

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

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Eli> I meant what should I do or not do as the user of the Python API in
Eli> question.

Eli> Or maybe I misunderstand what you are saying, sorry.

I think the idea is to warn Python developers that they should test
their code with future versions if they use this feature.
Normally we try to maintain compatibility, even when we've made mistakes.
But in this case, we suspect we may make changes and we don't want to
promise compatibility; but nor do we want to block this feature until
the symbol tables are changed, since that may not happen for some time.

I'm not totally wedded to this.  Maybe Doug could say more.

Tom

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

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Cc: sivachandra@google.com, gdb-patches@sourceware.org
> Date: Thu, 26 Apr 2012 07:54:15 -0600
> 
> I think the idea is to warn Python developers that they should test
> their code with future versions if they use this feature.
> Normally we try to maintain compatibility, even when we've made mistakes.
> But in this case, we suspect we may make changes and we don't want to
> promise compatibility; but nor do we want to block this feature until
> the symbol tables are changed, since that may not happen for some time.

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?

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

[Siva Chandra]

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.

AFAICT, if there is a change in future which can break an existing
Python program, or change the API behavior, then we mention this in
the docs and NEWS then. (?)

Thanks,
Siva Chandra
PS: I used the namespace block as an example and called it a
speculation.  It probably is not a speculation but a real plan!

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

[Eli Zaretskii]

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

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

[Doug Evans]

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/  ?

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

[Eli Zaretskii]

> Date: Fri, 27 Apr 2012 09:49:35 -0700
> From: Doug Evans <dje@google.com>
> Cc: tromey@redhat.com, gdb-patches@sourceware.org
> 
> >  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/  ?

I think omitting "to" makes it more correct English.

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

[Doug Evans]

On Fri, Apr 27, 2012 at 10:29 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Fri, 27 Apr 2012 09:49:35 -0700
>> From: Doug Evans <dje@google.com>
>> Cc: tromey@redhat.com, gdb-patches@sourceware.org
>>
>> >  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/  ?
>
> I think omitting "to" makes it more correct English.

Really?  Huh.
It's not important enough, so whichever "works for me".

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

[Siva Chandra]

[-- Attachment #1: Type: text/plain, Size: 817 bytes --]

On Fri, Apr 27, 2012 at 9:06 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 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 have modified the patch to use the exact same text as above.

2012-04-28  Siva Chandra Reddy  <sivachandra@google.com>

        * gdb.texinfo (Blocks In Python): Add a note saying that future
        improvements to GDB and its infrastructure can move symbols
        across blocks within a symbol table.

Thanks,
Siva Chandra

[-- Attachment #2: blocks_doc_patch_v2.txt --]
[-- Type: text/plain, Size: 822 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.950
diff -u -p -r1.950 gdb.texinfo
--- gdb.texinfo	25 Apr 2012 16:13:17 -0000	1.950
+++ gdb.texinfo	27 Apr 2012 19:20:13 -0000
@@ -24580,7 +24580,11 @@ detailed technical information on @value
 stack.
 
 A @code{gdb.Block} is iterable.  The iterator returns the symbols
-(@pxref{Symbols In Python}) local to the block.
+(@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.
 
 The following block-related functions are available in the @code{gdb}
 module:

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

[Eli Zaretskii]

> Date: Sat, 28 Apr 2012 00:56:52 +0530
> From: Siva Chandra <sivachandra@google.com>
> Cc: tromey@redhat.com, dje@google.com, gdb-patches@sourceware.org
> 
> >  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 have modified the patch to use the exact same text as above.

Thanks.  If everyone is happy, then so am I.

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

[Siva Chandra]

On Sat, Apr 28, 2012 at 12:21 PM, Eli Zaretskii <eliz@gnu.org> wrote:

> Thanks.  If everyone is happy, then so am I.

I think Doug has also OK-ed it.  If I do not see any objections, I
will commit it in couple of days.

Thanks,
Siva Chandra

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

[Siva Chandra]

Eli> Thanks.  If everyone is happy, then so am I.

Siva> I think Doug has also OK-ed it.  If I do not see any objections, I
Siva> will commit it in couple of days.

Committed now.

Thanks,
Siva Chandra