Re: [rfc] python API exposing inferior's frame stack.

[Thiago Jung Bauermann <bauerman at br dot ibm dot com>]

El mar, 10-03-2009 a las 21:35 +0200, Eli Zaretskii escribiÃ:
> > This patch allows a Python script to work with the inferior's frame
> > stack. For now, the only "entry point" for this API is the
> > gdb.selected_frame function.
> 
> Thanks.  I have a few comments about the documentation part of the
> patch.

Thanks for the review. The comments which I don't reply to below were
addressed.

> > +@defmethod Frame unwind_stop_reason
> > +Return an integer representing the reason why it's not possible to find
> > +frames older than this.
> 
> "older"?  You mean, higher in the call stack?

I don't know, which direction is "higher in the call stack"? :-)

> Is "older" widespread enough to be self-explanatory?

"older" is the name of the Frame method used to get the previous frame
(where "previous" is the convention used in the GDB source code), so it
has a good chance of being clear to the user of the Python API. In any
case, I reworded it to:

"Return an integer representing the reason why it's not possible to find
frames older (outer) than this."

What do you think?

> > +@defmethod Frame address_in_block
> > +Returns an address which falls within the frame's code block.
> > +@end defmethod
> 
> This is unclear to me.  Is there only one such address?  If not, why
> is that useful to get _an_ address?

The only use I have for this function right now is to obtain an address
to pass to the function gdb.find_pc_function, which returns a gdb.Symbol
object for the function containing the given address.

This usage directly reflects the way things are done in the GDB
internals. Perhaps I should depart from it, remove gdb.find_pc_function
and gdb.Frame.address_in_block and directly provide a gdb.Frame.function
method which returns the gdb.Symbol object for the function
corresponding to the frame?

It sounds like a better idea now that I think about it. But I'll have to
post a patch exposing inferior symbols before I can submit it upstream.

I'll remove gdb.Frame.address_in_block for now, then.

> > +@defmethod Frame older
> > +Return the frame immediately older (outer) to this frame.
> > +@end defmethod
> > +
> > +@defmethod Frame newer
> > +Return the frame immetidaely newer (inner) to this frame.
> > +@end defmethod
> 
> Suggest to use "higher" or "above" or "towards the outermost frame".
> Generally, try to use the terminology from  the "Examining the Stack"
> chapter of the manual.

IMHO, "inner" and "outer" are already conforming to the terminology from
the "Examining the Stack" chapter. It is a bit awkward to use "towards
the outermost frame" to describe these methods, e.g.:

"Return the next frame in the direction towards the outermost frame."

and

"Return the next frame in the direction towards the innermost frame."

Mmm... Now that I tried, doesn't sound too bad. But still I find my
original wording more direct and simpler to understand. What do you
think?

I'll post an updated patch when we agree on these points.
-- 
[]'s
Thiago Jung Bauermann
IBM Linux Technology Center