From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17562 invoked by alias); 15 Mar 2009 18:15:17 -0000 Received: (qmail 17546 invoked by uid 22791); 15 Mar 2009 18:15:15 -0000 X-SWARE-Spam-Status: No, hits=-2.8 required=5.0 tests=AWL,BAYES_00,SPF_PASS X-Spam-Check-By: sourceware.org Received: from e24smtp04.br.ibm.com (HELO e24smtp04.br.ibm.com) (32.104.18.25) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sun, 15 Mar 2009 18:15:09 +0000 Received: from mailhub1.br.ibm.com (mailhub1.br.ibm.com [9.18.232.109]) by e24smtp04.br.ibm.com (8.13.1/8.13.1) with ESMTP id n2FIC66x025138 for ; Sun, 15 Mar 2009 15:12:06 -0300 Received: from d24av01.br.ibm.com (d24av01.br.ibm.com [9.18.232.46]) by mailhub1.br.ibm.com (8.13.8/8.13.8/NCO v9.2) with ESMTP id n2FIFJYa1552538 for ; Sun, 15 Mar 2009 15:15:19 -0300 Received: from d24av01.br.ibm.com (loopback [127.0.0.1]) by d24av01.br.ibm.com (8.12.11.20060308/8.13.3) with ESMTP id n2FIF1u2025607 for ; Sun, 15 Mar 2009 15:15:02 -0300 Received: from [9.8.10.213] ([9.8.10.213]) by d24av01.br.ibm.com (8.12.11.20060308/8.12.11) with ESMTP id n2FIF1S4025571; Sun, 15 Mar 2009 15:15:01 -0300 Subject: Re: [rfc] python API exposing inferior's frame stack. From: Thiago Jung Bauermann To: Eli Zaretskii Cc: gdb-patches@sourceware.org In-Reply-To: References: <1236706351.11106.17.camel@localhost.localdomain> Content-Type: text/plain; charset=utf-8 Date: Sun, 15 Mar 2009 18:35:00 -0000 Message-Id: <1237133466.316.16.camel@localhost.localdomain> Mime-Version: 1.0 Content-Transfer-Encoding: 8bit X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2009-03/txt/msg00236.txt.bz2 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