From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 2211 invoked by alias); 12 Sep 2014 09:45:32 -0000 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 Received: (qmail 2201 invoked by uid 89); 12 Sep 2014 09:45:31 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-3.2 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD,SPF_HELO_PASS,SPF_PASS autolearn=ham version=3.3.2 X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-GCM-SHA384 encrypted) ESMTPS; Fri, 12 Sep 2014 09:45:30 +0000 Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s8C9jRfi001804 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Fri, 12 Sep 2014 05:45:27 -0400 Received: from blade.nx (ovpn-116-128.ams2.redhat.com [10.36.116.128]) by int-mx11.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s8C9jQwx028749; Fri, 12 Sep 2014 05:45:27 -0400 Received: by blade.nx (Postfix, from userid 1000) id 5369E2640D5; Fri, 12 Sep 2014 10:45:26 +0100 (BST) Date: Fri, 12 Sep 2014 09:45:00 -0000 From: Gary Benson To: Doug Evans Cc: gdb-patches , Pedro Alves Subject: Re: [PATCH 5/9 v7] Introduce common-regcache.h Message-ID: <20140912094526.GA17822@blade.nx> References: <1409320299-6812-1-git-send-email-gbenson@redhat.com> <1409320299-6812-6-git-send-email-gbenson@redhat.com> <21520.37315.16694.677898@ruffy2.mtv.corp.google.com> <20140911110231.GC17472@blade.nx> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-IsSubscribed: yes X-SW-Source: 2014-09/txt/msg00386.txt.bz2 Doug Evans wrote: > On Thu, Sep 11, 2014 at 4:02 AM, Gary Benson wrote: > > Doug Evans wrote: > > > Gary Benson writes: > > > > +/* Return the register cache associated with the thread specified > > > > + by PTID. This function must be provided by the client. */ > > > > > > Can you add a comment here explaining the ownership of the > > > memory object returned? E.g., is it cached "internally" to > > > the function so that the caller doesn't have to free it? > > > > That seems odd. We don't document other similar functions this > > way: I'm thinking GDB's get_current_arch, current_inferior, > > target_gdbarch, or gdbserver's current_process, > > current_target_desc. It seems the pattern is to note if the > > caller must free the object and to remain quiet otherwise. > > Yeah, but I never liked such things being implicit. I can't trust a > missing "caller must free" as being intentional. [One can equally > argue the presence of "caller must free" (or "not free") isn't > necessarily trustable, but such things don't change that often.] > > With a name like "get_current_foo", the "current" makes things less > implicit (at least to me). > > If we were using c++ then object ownership can (often, though not > always) be more clearly expressed and then such things can be more > reasonably left as being implicit in comments. But we don't have > that so if we're going to be cleaning things up, and maybe even > paying a little attention to API design, I figure IWBN to have > things be clearer than they are today. > > [Plus I get bitten time and again by taking gdb's existing practice > as something we actually want to keep. :-)] > > > How about I change the comment to "Return _a_pointer_to_ the > > register cache..."? (underlines for emphasis here). > > If one was going to add emphasis, I'd emphasize _the_. :-) I tried to figure out how to succinctly write what you're asking me to here but I'm stuck. Is there a function documented in this way in GDB I can use as an example? In the interests of keeping things moving I've pushed the patch with this comment: Return a pointer to the register cache associated with the thread specified by PTID. This function must be provided by the client. Thanks, Gary -- http://gbenson.net/