Welcome to the L-World Value Types early adopter's project !

What is the L-World Value Types project?

• The L-World Value Types project is a series of early prototypes for Value Types
  • builds on work of the previous Minimal Values Types prototype (MVT)
    • provides a new type which is: immutable, identity-agnostic, non-nullable, non-synchronizable, final
    • Value Types contained in References, other Value Types or in Arrays are flatten-able
    • Value Types can contain primitives or references
  • Allows value types to inter-operate with Object or "L-Type" descriptors

Target Audience

• Power users  - Java/JVM Language, Framework, Library authors/exports
  • who are comfortable with early experimental software
  • who recognize that everything in the experiment - the model, the classfile extensions, the byte codes is likely to change
  • who want to contribute to early exploration of Value Types
  • who will not build any products based on these prototypes
• Who are willing to provide feedback to the developers on a subset of Value Type features
• Who will provide use cases for the development team to experiment with optimizations

"L-World"

The previous MVT prototype maintained completely separate descriptors, "Q-Types", where value type signatures began with "Q" (similar to how Object descriptors begin with "L", i.e. "L-Types"). Data movement and manipulation of value types under the MVT prototype all required separate byte-codes. There were at one point 13 new internal byte codes, known as "v-bytecodes" since they are all started with "v". These are no more. What we have today, is an attempt to incorporate value types into L-type system to maximize backward compatibility with existing Objects and Interfaces, an "L-World" if you will:

• Value Types may be referred to by the same "L-Type" descriptors the VM has always operated on:
  • may pass a value type as a java.lang.Object or interface, through existing APIs
  • may implement interfaces with value types
  • identity-less: 
    • synchronization will fail with exception: IllegalMonitorStateException
    • reference equality with "==" (if_acmp<eq|ne>) always returns false, value equality requires using the "equals()" method
• There are only two new byte-codes, otherwise existing byte-codes have been engineered to accept and maintain value type characteristics (identity-less, flattenable, pass by value):
  • "default" - will create a new default value
  • "withfield"- allows updating value type fields via a copy-on-write semantic, i.e. new value based on the old value combined with new field value.

Recognize that the path to Valhalla is long, there are number of open issues facing value types. We wish to solve these incrementally. Fully generic specialization of value types with clear and sensible migration rules are going to take more than a single prototype.

"LW1" - Minimal L-World

Initial "least amount of work required" prototype with a number of hidden switches which need sensible defaults depending on the strategies decided upon, going forward. Highlights:

• Experimental source support via javac with "__ByValue" class declaration modifier
• Value Types cannot be used as parameterized types, i.e. current generic type declarations do not support primitives, nor value types at this point in time
• Type migration, including partial recompilation is not supported at this point

How to Try L-World Value Types:

Early Access Binaries

http://jdk.java.net/valhalla/

Repository and Build Instructions

To create a new local repository, based on "lworld" branch:

hg clone http://hg.openjdk.java.net/valhalla/valhalla valhalla-lworld

cd valhalla-lworld

hg defpath du <openjdkname> 

hg update -r lworld // name of branch

To update repository: 

cd valhalla-lworld

hg pull

hg update -r lworld  // name of branch

To build repository

bash configure

make images

Instructions for working with branch repositories: http://cr.openjdk.java.net/~chegar/docs/sandbox.html

Note: Valhalla is a child of the jdk/jdk repository, to keep current with latest OpenJDK development.

Programming Model

CMH: Example code

Sample JMH benchmarks: http://mail.openjdk.java.net/pipermail/valhalla-dev/2018-June/004380.html

Run Experimental L-World

• java -XX:+EnableValhalla <Test>
• Further experimental flags can be found here

Filing Bugs

• Send email to valhalla-dev@openjdk.java.net with bugs or small use cases for optimization

Limitations

• platforms: x64 Linux, x64 Mac OS X, Windows
• no support for value class with no instance fields
• no support for atomic fields containing value types (work-in-progress for an update)
• no support for @Contended value type fields
• static fields are not flattenable
• no AOT, CDS, ZGC, serviceability agent
• -Xint and C2 only, no C1, no tiered-compilation, no Graal
• unsafe field accessor APIs are not supported for value types
• interpreter is not optimized, focus is on JIT optimization
• Need additional USE CASES for optimizations
• Working on additional test cases

References

• Draft Java Virtual Machine Specification Value Type changes
• http://cr.openjdk.java.net/~chegar/docs/sandbox.html  (instructions for working with branch repositories)