Re: trace/events: DECLARE vs DEFINE semantic

[Masami Hiramatsu <mhiramat@redhat.com>]

Steven Rostedt wrote:
>>> I think the kernel developers are smart enough to figure out that these
>>> macros are not a typical DECLARE/DEFINE that is elsewhere. But I think
>>> using the DECLARE/DEFINE names will give them a better idea of what is
>>> happening than to make up something completely new.
>>
>> In my opinion, re-using a well-known keyword (e.g. DECLARE/DEFINE) but
>> applying a different semantic to what is generally agreed upon is a
>> recipe for confusing developers and users, who will skip the review of
>> some pieces of code assuming they already know what "DECLARE" and
>> "DEFINE" stands for.
>>
>> I argue here that the content of trace/events/ headers are _not_ per se
>> declarations nor definitions, and hence they should not confuse people
>> by using inappropriately well-known keywords. They are actually more
>> evolved macros that can be turned in either a declaration or definition,
>> depending if CREATE_TRACE_POINTS is declared.
> 
> And I argue that the semantics here are not too far off to what those
> are. Yes, these macros behave differently if CREATE_TRACE_POINTS is
> declared or not, but I argue that the average (and below average) kernel
> developer is smart enough to understand this difference.
> 
> 
>>
>> When I created the markers/tracepoints, Andrew Morton explained to me
>> the importance of distinguishing DECLARE vs DEFINE macros. I would
>> really like to hear his point of view on the current question.
> 
> I would like to hear Andrew's comments too, as well as anyone else.
> Randy Dunlap seemed to already approve of these naming conventions, and
> he's a pretty picky person too.
> 
> Randy, do you agree that the use of DECLARE/DEFINE here is fine, or do
> you think that we should come up with a better naming. I do not want to
> add any needless abstraction layer for the sake of naming. These macros
> are confusing enough without that.
> 
> Or do you (or anyone else) have a better name?

How about renaming DEFINE_EVENT to TRACE_EVENT_CLASS?

DECLARE_EVENT_CLASS(y, ...)	declare an event-class y
TRACE_EVENT_CLASS(x, y, ...)	define/declare a trace event x from event-class y
TRACE_EVENT(x, ...)		define/declare a trace event x

Thus TRACE_EVENT_* implies that this macro will be expanded
to both of definition and declaration.
I don't think separating it is good idea from the viewpoint
of maintaining code.

Thank you,

-- 
Masami Hiramatsu

Software Engineer
Hitachi Computer Products (America), Inc.
Software Solutions Division

e-mail: mhiramat@redhat.com