Proposal: Use new JDK_EXPORT decorator instead of JNIEXPORT

[David Holmes]

Hi Magnus,

On 10/12/2018 11:19 pm, Magnus Ihse Bursie wrote:
> I propose that we introduce a new define, available to all JDK native 
> files (Hotspot included), called JDK_EXPORT. The behavior of this symbol 
> will be very similar (as of now, in fact identical) to JNIEXPORT; 
> however, the semantics will not.
> 
> Currently, we "mis-use" the JNIEXPORT define to mark a function for 
> exporting from the library. The problem with this is that JNIEXPORT is 
> part of the JNI interface, and is supposed to be used when C programs 
> interact with Java. And, when doing this, the function should be fully 
> decorated like this: "JNIEXPORT foo JNICALL".

I've seen a lot of the emails on this issue and I don't fully understand 
what has been going wrong. But the intent is obviously the JNIEXPORT 
represents what is needed to export this function for use by JNI, while 
JNICALL defines the calling convention. I agree there may be some 
mistmatch when functions are actually not intended for general export 
outside the JDK but are only for internal JDK use.

> We do have many such JNI exports in our native libraries, but we also 
> have a lot of other, non-JNI exports, where one native library just 
> provides an interface to other libraries. In these cases, we have still 
> used JNIEXPORT for the functionality of getting the function exported, 
> but we have not been consistent in our use of JNICALL. This has caused 
> us way too much trouble for something that should Just Work<tm>.

Are you suggesting that the interface between different libraries in the 
JDK should not be a JNI interface? Is this because you think the 
functions in these libraries are only for JDK internal use or ... ??

> I therefore propose that we define "JDK_EXPORT", with the same behavior 
> as JNIEXPORT (that is, flagging the function for external visibility in 
> the resulting native library), but which is *not* supposed to be 
> exported to Java code using JNI, nor supposed to be decorated with 

Just a clarification there. JNI functions are not exported to Java code, 
they are exported to native code. Java code can declare native methods 
and those native methods must be written as JNI functions, but that's 
not what we are discussing. Libraries expose a JNI interface (a set of 
functions in the library) that can be called by application native code, 
using JNI.

> JNICALL. All current instances of JNIEXPORT which is not pure JNI native 
> functions should be changed to use JDK_EXPORT instead.
> 
> I further propose that this macro should reside in a new file "jdk.h", 
> placed in the new directory src/java.base/share/native/include/internal. 
> This header file path will automatically be provided to all native 
> libraries, but not copied to the JDK being built. (The existence of a 
> "include/internal" directory with this behavior has been discussed 
> before. There are more files that ought to be moved there, if/when it is 
> created.) I believe in many cases the #include "jni.h" can be just 
> modified to #include "#jdk.h", since most native code will not require 
> "jni.h" unless actually doing JNI calls -- most have included this file 
> to get the JNIEXPORT macro, which would explain the pervasive use of 
> #include "jni.h" in our code base.

jni.h also defines all of the types used by the JNI. Those types are 
pervsive to the native code used throughout the JDK.

> Thoughts?

I think we need to understand the problems on Windows that prompted all 
this. Then I think we need to look at exactly how jni.h and JNIEXPORT 
etc are being used and understand whether this is truly an exported 
interface or not.

Cheers,
David

> /Magnus
>