Improving the documention of the JVM implementation interface

[Mikael Vidstedt]

As Steve says, improving and clarifying the the dependencies and 
interaction points between the JVM and the libraries is something I'm 
happy to support. The JVM_* functions already have some documentation, 
but even there I'm sure there are things that can be clarified, and I 
fully agree that things like Attach functionality could use some 
documentation work.

One thing I'd like to stress is that the goal of this project should not 
be to lock down the interface between the JVM and the JDK. Even though 
we should for a number of different reasons try to keep the interfaces 
changes to a minimum, we need to preserve the right to change them 
without having to go through lengthy standardization processes etc. I 
don't think that contradicts the goal of this project though.

I'm sure there are people who have been involved in projects where 
documentation like this would have been very helpful. If at all possible 
I'd like to encourage you to share your thoughts on this and if possible 
help us out going forward.

Thanks,
Mikael



On 2011-11-29 15:30, Steve Poole wrote:
> On Thu, 2011-11-24 at 11:26 +0800, Krystal Mok wrote:
>> Hi Steve,
>>
>>
>> There's been some efforts in this area before. There's an OpenJDK
>> project called "Common VM Interface" [1], ran by Dr Andrew John
>> Hughes. One of the earlier notes can be found at [2]. The aims of this
>> project seems to be in the same direction as what you're looking for.
> Hi Krystal - sorry for the delay in responding: been somewhat email
> server challenged.    Its possible the cmvi project could be used to do
> this work but it seems very quiet at the moment.  Besides, this proposal
> is about documenting what exists today,  so I'd rather have the
> conversation on a mailing list that the people who know frequent :-)
>>
>> Xi Yang has been working on integrating OpenJDK class libraries into
>> Jikes RVM this year. This work also needed a definition of the VM
>> interface in OpenJDK. He's made quite a lot of progress already, so he
>> might be able to help out with this documentation proposal. I'm cc'ing
>> this mail to him.
>>
>>
>> - Kris
>>
>>
>> [1]: http://openjdk.java.net/projects/cvmi/
>> [2]: http://mail.openjdk.java.net/pipermail/cvmi-dev/2008-July/000006.html
>>
>> On Wed, Nov 23, 2011 at 10:29 PM, Steve Poole
>> <spoole at linux.vnet.ibm.com>  wrote:
>>          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
>>
>>
>>
>>
>