From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.tuxdriver.com (charlotte.tuxdriver.com [70.61.120.58]) by dpdk.org (Postfix) with ESMTP id 8E8131B426 for ; Mon, 3 Dec 2018 17:48:07 +0100 (CET) Received: from cpe-2606-a000-111b-405a-a193-cb97-58ba-1c15.dyn6.twc.com ([2606:a000:111b:405a:a193:cb97:58ba:1c15] helo=localhost) by smtp.tuxdriver.com with esmtpsa (TLSv1:AES256-SHA:256) (Exim 4.63) (envelope-from ) id 1gTbV1-0000vB-Cr; Sun, 02 Dec 2018 18:50:19 -0500 Date: Mon, 3 Dec 2018 11:47:24 -0500 From: Neil Horman To: David Marchand Cc: dev@dpdk.org, Timothy Redaelli Message-ID: <20181203164724.GA12316@hmswarspite.think-freely.org> References: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.10.1 (2018-07-13) X-Spam-Score: 0.3 (/) X-Spam-Status: No Subject: Re: [dpdk-dev] Marking symbols as experimental in the headers only X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 03 Dec 2018 16:48:07 -0000 On Mon, Dec 03, 2018 at 02:01:02PM +0100, David Marchand wrote: > Hello Neil, > > Looking at > http://doc.dpdk.org/guides/contributing/versioning.html#experimental-apis, > is there a real need to mark both the definition and the declaration of a > symbol with the __rte_experimental marker ? > When I initially wrote the feature I marked both the function prototype and its definition with the macro to be consistent, as I like to make both declaration and definition look visually simmilar, just to ease readability, but I'm not bound to doing it that way per-se As to weather or not you can only mark the declaration as experimental, I'm not 100% sure. I think thats an artifact of the compiler. That is to say, the macro expands to a compiler attribute that is applied at compile time, and checked at link time, and I'm not sure what clang or gcc will do if there is a discrepancy between the attributes listed in the declaration and the definition. I would say, give it a try, and if you can demonstrate that adding the attribute only to the declaration results in a link-time warning when external code attempts to call an experimental function, I would have no problem handling it that way. > My understanding is that the whole point of having this marker is so that > rte_compat.h check trigger warnings when trying to use such a symbol from > the caller side. More specifically, its there so that when external code attempts to make a call to the experimental function, the compiler warns the user about said usage. > As long as the header where the symbol is published is included from the > file that defines the symbol, then the forward declaration ensures the > symbol will catch the tag, right ? > Not 100% sure on that. I say that because the attribute adds a note in the object file of the function definition, and at link time its checked so that calls to that function generate warnings. What needs to happen is that the deprecation note needs to make its way into the definitions object code. If that can be accomplished by just annotating the declaration, thats great, but I would suspect that its more likely that the definition needs to have the tag more than the declaration. I've been wrong before though, so likely some experimentation is called for here. > I would prefer marking the symbols only once in the header and write this > as the recommended way in the documentation. > > Do you see any issue doing this ? > I'm fine with it, as long as (as I note above), you can demonstrate that deprecation warnings are still issued to experimental api users if you only mark the declaration as __rte_experimental > > We have found an inconsistency, with a symbol marked as experimental in its > .c but not the .h ... will come up with a fix later. > > > -- > David Marchand