Improving the documention of the JVM implementation interface

[Steve Poole]

Hi all,  I've been talking to Mikael Vidstedt and a few other Oracle
luminaries about improving the documentation of the  interface between
the JVM and the rest of the SDK.

We wanted to make that discussion public hence this post.  I'll start
and Mikael can jump in.

What I'm trying to do is simply gain some agreement on what code is JVM
implementation specific and what isn't.  Then, where this JVM
implementation specific code interacts with the SDK, improve the
documentation.

A few examples to consider...

JVM_* entry points in the VM that are there for the class library code
to call: these are not part of the public JNI spec - I'd like to get
them documented in more detail.

These extra entry points can blur the line between the JVM and the class
libraries: sometimes making  it's difficult to work out if the "real"
API is the C entry point or the calling Java class. To put it another
way  - there is Java code that is intentionally JVM implementation
specific.   I'd like to get that status documented.

Another similar example is where Hotspot code leaks out of the JVM into
the class libs and tools.   The Late Attach API is a good (or is that
bad) example. Sometimes it's difficult to work out if that leakage is
intentional or inadvertent.  I'd like to get that status documented too.

So to recap:  what I'd like to do is discover and document the API
between the JVM implementation specific code and everything else.
Hopefully in the process improving everyone's awareness and getting some
common agreement over actual behaviour or design versus intention.  This
work might discover areas that could benefit from improved interface
design and some form of  refactoring but that would be for later.


Thanks

Steve