Improving the documention of the JVM implementation interface
spoole at linux.vnet.ibm.com
Tue Dec 6 06:22:20 PST 2011
On Fri, 2011-12-02 at 14:59 +0100, Mikael Vidstedt wrote:
> 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. The JVM_* functions would be a great place to start
improving the doc since it's already a known, shared, interface.
I'd also like to use a doc tool to create nice readable doc - what do
people think about updating jvm.h with doxygen style comments and then
using doxygen to create the docs?
> 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" , ran by Dr Andrew John
> >> Hughes. One of the earlier notes can be found at . 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
> >> : http://openjdk.java.net/projects/cvmi/
> >> : 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
More information about the hotspot-dev