Re: [dpdk-dev] Marking symbols as experimental in the headers only

[Neil Horman <nhorman@tuxdriver.com>]

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