Re: [ECOS] Namespace pollution

["Gary D. Thomas" <gary dot thomas at mind dot be>]

On Tue, 2003-03-04 at 08:28, Bart Veer wrote:
> >>>>> "Gary" == Gary D Thomas <gary dot thomas at mind dot be> writes:
> 
>     Gary> Jonathan,
>     Gary> I've run into a problem [near and dear to your heart] - a
>     Gary> place where the eCos namespace (via include files) intrudes
>     Gary> on an application. The problem is in <pthread.h>. This
>     Gary> particular application happens to have a typedef for the
>     Gary> symbol "destructor", which causes this prototype to fail:
> 
>     Gary> // Create a key to identify a location in the thread specific data area.
>     Gary> // Each thread has its own distinct thread-specific data area but all are
>     Gary> // addressed by the same keys. The destructor function is called whenever a
>     Gary> // thread exits and the value associated with the key is non-NULL.
>     Gary> externC int pthread_key_create (pthread_key_t *key,
>     Gary>                                 void (*destructor) (void *));
> 
>     Gary> So, the question(s) are:
>     Gary>  * Who's at fault here?  (the application or the kernel)
>     Gary>  * How best to solve it?
> 
>     Gary> As a work-around, I've modified that particular include file 
>     Gary> to avoid this problem (renaming destructor as _destructor).  
> 
>     Gary> n.b. This is a portable application from outside the eCos world,
>     Gary> so I don't want to have to change it, if possible.  If, on the
>     Gary> other hand, this is truly an application issue, I'll gladly take
>     Gary> it up with the [application] maintainers.
> 
> I believe the "correct" solution is to just remove the argument names
> from the header files, i.e. change <pthread.h> to :
> 
>      externC int pthread_key_create (pthread_key_t*, void (*)(void*));
> 
> Such argument names are not needed in function prototypes, only in the
> implementation. They only serve as a form of documentation - and on
> occasion that can be very useful.
> 
> Another way of tackling the problem involve careful use of underscores
> as you have done, e.g.:
> 
>      externC int pthread_key_create (pthread_key_t* _key,
>                                      void (*_destructor)(void*));
> 
> That reduces but does not eliminate the problem. Yet another approach
> is to put the argument name in comments:
> 
>      externC int pthread_key_create (pthread_key_t* /* key */,
>                                      void (* /* destructor */)(void*));
> 
> but that is not actually very readable, so much of the documentation
> value is lost.
> 
> My preferred approach is to leave out the argument name most of the
> time, but where has it special documentation value put it in comments.
> However I don't guarantee that I have been consistent about this in
> all my code.

Thanks.  I know that this is a sticky problem - everyone seems to
have their own opinion about what's "best" :-)

I like having the names in there.  Certainly if the names are well
chosen, they can provide a lot of useful [documentary] information.
I find using comments within the prototype very distracting though.

I'll opt for the __XX approach, since it's no worse than what was
already in place and probably better.

-- 
.--------------------------------------------------------.
|       Mind: Embedded Linux and eCos Development        |
|--------------------------------------------------------|
| Gary Thomas              email:  gary dot thomas at mind dot be   |
| Mind ( http://mind.be )  tel:    +1 (970) 229-1963     |
| gpg: http://www.chez-thomas.org/gary/gpg_key.asc       |
'--------------------------------------------------------'


-- 
Before posting, please read the FAQ: http://sources.redhat.com/fom/ecos
and search the list archive: http://sources.redhat.com/ml/ecos-discuss