Re: C native layer (pre-announcement)

[Brian Jones]

"Dr. Torsten Rupp" <address@hidden> writes:

> Currently there is a discussion to merge some or all of the native
> functions with the GCJ project. 

It's come up in the past.  The essential problem, for lack of a better
term, is that because underlying code is not shared that native bugs
must be fixed in two source trees.

> Because this will probably have some influence to the changes I made
> to the GNU classpath sources I want to post the following read-me in
> this list before I check-in the new sources. 

It would be a good idea to post the "patch" to the mailing list first
by using 'cvs diff -u' due to the size.  Except for one minor
directory name change I have no complaints.

> The GNU classpath native layer
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 
> To enable GNU classpath to run on a diverse array of different hardware
> platforms, a new native software layer has been added. This layer hide all
> machine and hardware dependent issues except common available definitions,
> which are ANSI C functions. For each targets system where the GNU classpath
> library is to be used, a specific set of native layer functions have to be
> provided. A generic set of functions is provided for Unix like systems
> (currently tested only with Linux). For a new target system, some or
> all native layer functions have to be rewritten. The following scheme
> illustrate the native layer.
> 
>              Java API
>        ----------------------
>       |    Java classes      |
>       | -------------------- |
>       |  C native functions  |
>       | -------------------- |
>    >> |    C native layer    |  <<
>       | -------------------- |
>       |   operating system   |
>       | -------------------- |
>       |       hardware       |
>        ----------------------
> 
> The C native layer is implemented as a set of C pre-processor native macros.
> These macros expand to the appropriated native code. Macros are used
> instead function calls to give optimal performance and small code size.
> Of course in special cases, a macro can also expand to a function call
> if this is needed. This approach provide a flexible and efficient
> implementation of the native layer.

When this becomes part of Classpath would you mind adding this
information to the hacker's guide or as a lesser option adding this
README to CVS as well?

> The directory and file structure is as follows.
> 
>    native
>     ...
>      |
>      |--- target

Should this 'target' be called 'macros'?

>      |      |
>      |      |--- Linux
>      |      |      |--- target_native_<module name>.h
>      |      |      |--- ...
>      |      |     ...
>      |      |--- ...
>      |      |--- generic
>      |      |      |--- target_generic_<module name>.h
>      |      |      |--- ...
>     ...    ...    ...
> 
> 
> When writing native code, please take care with the following.
> 
>   - Use _only_ ANSI C specific functions directly which are available
>     on all target systems with the same parameters, e. g. strdup() is
>     not an ANSI C function, thus is is not available on all systems; mkdir()
>     expect on some systems different parameters.
> 
>     !!!Do NOT use this functions in your native code!!!

I don't think I have a handy reference for what ANSI C functions are
generally available on most systems with the same arguments.  Where
would I look?

>   - Avoid _all_ OS specific data types and constants,
> e. g. structures or error numbers. Instead, wrap them in a native
> macro and convert the values to basic scalar types like char, int,
> double or long.

I'd like to see how you deal with the 'tm' structure for time/date
data.

>   - Avoid - if possible - non-reentrant functions. Non-reentrant functions
>     cause strange problems on some multitasking systems.

I'm confused about when to worry about this.  Does it matter for
synchronized methods?  Does it matter for all native code?  Does ANSI
define what is reentrant?

That's all my thoughts for now,
Brian
-- 
Brian Jones <address@hidden>