Fwd: indy-javadoc-mlvm-1024

[John Rose]

The 292 EG has been meeting approximately weekly since JavaOne.  Here is the summary of results, FYI.

Now you know what that giant mercurial push was.

-- John

Begin forwarded message:

From: John Rose <john.r.rose at oracle.com>
Date: October 24, 2010 4:17:38 AM PDT
To: jsr-292-eg at jcp.org
Subject: indy-javadoc-mlvm-1024

Here is a fresh spin of the javadoc for JSR 292.

It attempts to closely document the EG's current status, as of last Friday.  I think it addresses (one way or another) each issue on our issue list, in an up-to-date manner.

Unless something is very wrong in this specification, it is likely to be the one we will use as a baseline for RI and TCK engineering, moving forward.  (Comment soon.  Next month is not soon.  This week is soon.)

We can and will make changes to to the spec., but it will become more difficult to do so as the RI moves along the release process.

Nearly all annotations of the form "PROVISIONAL API" have been removed, because I believe we are at consensus on most points of the API.  A few remain (listed below.)

The most notable changes are:
- a large number of deletions (see below)
- a clear update for bootstrap methods (both adding and removing features)
- a new organization of call site types (which is the proposal requested at last Friday's concall)

Here are the call site types:
- CallSite (regular mutable variable, and also the common supertype)
- ConstantCallSite (simple lockdown of CS)
- VolatileCallSite (volatile target, equipped with an invalidation protocol)

A few points are still marked provisional:
- the constructor for an empty Callsite, which now requires a MethodType (no untyped call sites)
- MethodHandle.withTypeHandler (the javadoc now contains a working varargs example)
- MethodHandles.explicitCastArguments
- MethodHandles.constant & identity (K and I combinators, for ldc simulation etc.)
- MethodHandles.filterReturnValue (necessary companion to filterArguments)
- MethodHandles.asInstance (SAM conversion, strongly requested by Lambda)
- MethodHandles.AsInstanceObject (inverse to SAM conversion, also requested)
- VolatileCallSite (javadoc includes a working dependency application, for Remi)
- extra static arguments for bootstrap methods (CONSTANT_InvokeDynamic tag 18)

The spec. is written assuming we will agree on the extra BSM arguments.  (I had to write it one way or the other.)  There are caveats saying that one format or the other will win by PFD.  Let's decide soon, by evaluating use cases and seeing what the class file contents would look like.

Here are other new parts of the API:
- the package-info page is brought up to date
- multiple BSM invocations are gone; this removed much complexity from the spec. (long live call sites)
- a BSM can only return a CallSite or subtype thereof
- the first argument to a BSM is always a Lookup object
- it's followed by the name, type, and optional extra argument(s)
- these types are gone: LinkagePermission, Dependency, DependencyProvider, MethodHandleProvider, JavaMethodHandle
- Linkage is heavily deprecated and stripped of functionality, except (for the moment) global BSMs.
- these types are also gone: @BootstrapMethod, InvokeDynamic; perhaps they can reappear in JDK 8
- many previously deprecated methods are removed (mostly old aliases, like invokeVarargs for invokeWithArguments)
- CallSite can no longer have a null target, not even at creation (memory model effects for type adoption were bad)
- language about binding call sites to invokedynamic is adjusted to allow for free-floating call sites
- doc for "toString" methods is made vague.
- doc for convertArguments is updated (still not perfect)
- explicitCastArguments is added
- access rules for Lookup are defined more clearly, and drop the controversial nestmate rule (sigh)
- added appendParameterTypes to MethodType (usability for chain-style expressions)

For the moment, the old syntax of mh.<T>invokeExact() is visible.
This will change globally to (T)mh.invokeExact when b116 of the RI is promoted.

http://cr.openjdk.java.net/~jrose/pres/indy-javadoc-mlvm-1024.zip
http://cr.openjdk.java.net/~jrose/pres/indy-javadoc-mlvm

Best wishes,
-- John


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/mlvm-dev/attachments/20101024/758ebb1f/attachment-0001.html