rtems/src/scheduler* code convention issue

[Joel Sherrill]

On 5/30/2014 8:13 AM, Gedare Bloom wrote:
> On Fri, May 30, 2014 at 9:04 AM, Joel Sherrill
> <joel.sherrill at oarcorp.com> wrote:
>> On 5/30/2014 2:43 AM, Peter Dufault wrote:
>>> On May 29, 2014, at 17:47 , Gedare Bloom <gedare at rtems.org> wrote:
>>>
>>>> You understood precisely. I think it was not permitted in C90 perhaps?
>>>> We should revisit it, but I think historically all variables are
>>>> declared at the top of the function.
>>> I'll dig up K&R, but I'm 95% sure it's been supported from the beginning.  What hasn't always been supported is declaring variables anywhere other than after an opening bracket:
>>>
>>> /* Local block */
>>> {
>>>       invoke_foo();
>>>       int i;
>>>       invoke_bar(&i);
>>>       /* ... */
>>> }
>>>
>>> The argument for permitting declaration inside brackets (not as above, but as allowed by K&R) is to declare variables in as restrictive a scope as possible.  The argument against is shadowing variables and getting subtle errors.
>> I don't know if we have it on but gcc has a shadowing warning which
>> is pretty effective. I did a code review for a project and learned they
>> had disabled warnings "because there were too many." When I turned
>> them back on, there were 1000s and among them:
>>
>> + parameters shadowing global variables.
>> + outer scope local variables shadowing global variables.
>> + inner scope local variables (from macros) shadowing local variables
>>
>> GCC spotted all of the above. I am pretty confident in GCC's shadowing
>> detection.  If we want to allow/encourage this, we need to turn
>> the warning on.
>>
> Thanks for the discussion on this. I will put a rule as declaring
> variables at the start of a block, and not to shadow variables.
>
> Whether we want to encourage variables in nested scopes remains open
> for discussion, but I think we should allow it at least.
>
>> Also we need to remember to write down that macro parameters
>> start with an _ so as to avoid name collision. The project I reviewed
>> didn't follow that rule.  They also didn't have naming rules which
>> prevented collisions between local, global, and parameters.
> I'll add a note about it.
In case there is not a rule about naming. The public API routines follow
a standard API like POSIX or *BSD or start with rtems_. In the 4.7-4.9
timeframe, I cleaned up a lot of support code to do this like the
stack checker, cpu use, period use, etc.

If a method starts with rtems_, then it should be assumed to be
available for use by the application and have documentation in
the User's Guide.

Internal methods (inside score, sapi, rtems, and posix with
hope that libcsupport and RTEMS specific filesystems and other
cpukit code follow along) are named by "package" and "method".
If you think C++, you get package::method. But _[A-Z] indicates
where a namespace separator would be. The leading _ makes it
private.

_Chain_Get_first is a private method named Get_first in Chain.
In C++, it might be _Chain::Get_first.

Many modules are essentially classes which encapsulate a
data structure and all accesses with methods. The first
parameter to most methods is then going to be logically
an instance pointer like C++ this.

I don't know if I am rambling, repeating things documented
now, or something else. But hopefully core dumping like
this helps.
> -Gedare
>
>>> Peter
>>> -----------------
>>> Peter Dufault
>>> HD Associates, Inc.      Software and System Engineering
>>>
>> --
>> Joel Sherrill, Ph.D.             Director of Research & Development
>> joel.sherrill at OARcorp.com        On-Line Applications Research
>> Ask me about RTEMS: a free RTOS  Huntsville AL 35805
>> Support Available                (256) 722-9985
>>

-- 
Joel Sherrill, Ph.D.             Director of Research & Development
joel.sherrill at OARcorp.com        On-Line Applications Research
Ask me about RTEMS: a free RTOS  Huntsville AL 35805
Support Available                (256) 722-9985