Observing Project Valhalla

📥 Download source code

About the Speaker

• Cay Horstmann
• Author of Core Java (14 editions since 1996), Java/JavaScript/Scala for the Impatient, etc.
• Java Champion
• https://horstmann.com

Values and References

• Ever since Java 1.0: Eight primitive types byte short int long float double boolean char
• Everything else is a reference type
• Primitive types are “flat”—no indirection
• And “dense”—no headers
• Performance benefits
  • Memory savings
  • Better locality
  • Less GC work
• What if we want more primitives, erm, values?
• E.g. currency, measures, date/time, short/long floats, points, complex, tuples
• “Codes like a class, acts like an int”
• Valhalla was born July 10, 2014 and has gone through many iterations
  • Surface syntax has changed many times, e.g. inline classes
  • There used to be different bytecodes, e.g. Q codes for values
  • “Virtuous collapse” from Peak of Complexity in 2024

Value Classes

• JEP 401: Value class gives up identity
• Instance fields are final
• ==, hashCode derived from fields, not address
• No synchronized methods
• JVM may (but doesn’t have to) optimize layout/performance
• Many value classes will be records:

  public value record Point(double x, double y) {
     public Point moveBy(double dx, double dy) { return new Point(x + dx, y + dy); }
  }

• Abstract value class can be extended by value or identity classes

Building Valhalla

• No need to build for simple experiments—use the sandbox https://javaalmanac.io/jdk/valhalla/
• A recent build may be on https://jdk.java.net/valhalla/
• Easy to build on Linux:

  git clone https://github.com/openjdk/valhalla/
  cd valhalla
  bash configure

• Install any missing packages
• Run

  make clean images
  

• The JDK build is in valhalla/build/linux-x86_64-server-release/images/jdk
• If you use SDKMAN!

  sdk install java valhalla /path/to/valhalla/build/linux-x86_64-server-release/images/jdk
  

Running Valhalla

• value class syntax is supported in current Valhalla build
• Be sure to enable preview:

  javac --enable-preview --source 27 ...
  java --enable-preview ...
  jshell --enable-preview
  

• Easy thing to try: Brownian motion

  Point p = new Point(0, 0);
  for (int i = 0; i < ITERATIONS; i++)
      p = p.moveBy(Math.random() - 0.5, Math.random() - 0.5);
  IO.println(p);
  

• After 100_000_000 iterations:

  time java --enable-preview withvalhalla.Brownian
  Point[x=619.9117803091456, y=2227.141928668786]
  real    0m7.806s
  

• Timing without Valhalla: 0m8.178s
• So, what does Valhalla buy us?

Object Allocations

• Object header on 64-bit VM: 12 bytes
• Two doubles: 16 bytes
• 4 bytes padding for total of 32 bytes per Point heap object
• 100_000_000 points ≈ 2.98GiB
• Pre-Valhalla: Garbage collector is busy
• To see, run

  java --enable-preview -XX:StartFlightRecording=filename=novalhalla.jfr novalhalla.Brownian
  

• Load novalhalla.jfr into Java Mission Control
• Open Memory tab
• See allocations for 100_000_000 Point objects (close to 3GiB), busy GC
• Repeat with Valhalla version
• 24MiB allocated, no GC activity 😻

JIT Code Disassembly

• But why isn’t Valhalla faster?
• Let’s look at the generated code
• Download hsdis-amd64.so from https://www.chriswhocodes.com/hsdis/ into current directory, then

  export LD_LIBRARY_PATH=.
  java --enable-preview -XX:+UnlockDiagnosticVMOptions -XX:+PrintAssembly \
  -XX:+LogCompilation -XX:LogFile=novalhalla.log novalhalla.Brownian
  

• View the logs with JITWatch

  GDK_SCALE=2 java --enable-preview -jar jitwatch-ui-1.5.0-shaded-linux-x64.jar &
  

• Click Open Log, then Start
• Repeat with withvalhalla
• Look at Brownian.main. Valhalla version doesn’t do any object allocation

Hotspot

• javac generates bytecodes
• java interprets bytecodes...
• ...and compiles them into machine code
• Opcodes at https://shell-storm.org/x86doc/
• C1 compiler: simple optimizations, speeds up startup time
• C2 compiler: more complex optimizations for long-running programs
• “Hot” methods are compiled (i.e. frequently called—C1: 1,500, C2 10,000)
• “Hot” loops are compiled
• Methods may be inlined, loops unrolled
• Objects may be stack allocated—even without Valhalla if they don’t “escape”
• In our case:
  • We see inlining (with and without Valhalla), stack allocation (with Valhalla)
  • But the inlined Math.random is much more expensive 😞

Benchmarking

• Use JMH (Java Microbenchmark Harness) for accurate timing, JVM warmup
• Make project with

  mvn archetype:generate \
    -DinteractiveMode=false \
    -DarchetypeGroupId=org.openjdk.jmh \
    -DarchetypeArtifactId=jmh-java-benchmark-archetype \
    -DgroupId=com.horstmann \
    -DartifactId=valhalla-benchmark \
    -Dversion=1.0
  

• In POM, set javac.target to 27 and add this inside configuration of maven-compiler-plugin:

  <compilerArgs>
     <arg>-verbose</arg>
     <arg>--enable-preview</arg>
     <arg>-proc:full</arg>
     <arg>--add-exports</arg>
     <arg>java.base/jdk.internal.vm.annotation=ALL-UNNAMED</arg>
  </compilerArgs>
  

• Compile and run:

  cd benchmark
  mvn clean install
  java --enable-preview -jar target/benchmarks.jar Benchmark1
  

Too Good to Be True?

• Instead of random movement, transform tweaks and swaps x and y:

  /* value */ record Point(double x, double y) {
      ...
      public Point transform() { return new Point(y + 1, 0.5 - x); }
  }

• Set p = p.transform() 10_000_000 times
• Amazing result 🤩

  Benchmark                         Mode  Cnt      Score      Error  Units
  c.h.novalhalla.Benchmark1.work    avgt   25  59172.750 ± 720.373  us/op
  c.h.withvalhalla.Benchmark1.work  avgt   25      0.006 ±   0.001  us/op
  

• Valhalla is good, but can it be that good?

Fixing the Benchmark

• With Valhalla, inlined call to transform unrolls loop
• And Hotspot notices that p.transform().transform().transform().transform() equals p!
• Exercise: Watch JIT
• Remedy: More complex transform
• If using random numbers, precompute them

  Benchmark                         Mode  Cnt      Score      Error  Units
  c.h.novalhalla.Benchmark2.work    avgt   25  62759.141 ± 510.204  us/op
  c.h.withvalhalla.Benchmark2.work  avgt   25  15611.086 ± 250.861  us/op
  

• Solid result: Value type are performant 👍
• And remember the lower memory footprint! 😻

Null-Restricted Types

• Value type variables can be null:

  Point target = null // Ok;
  

• Flattened layout needs a bit for nullness
• If never null, escape analysis can often optimize locally
• But not inside objects, arrays
• Null-restricted type: Value class type that can’t be null:

  Point! origin = new Point(0, 0); // Syntax may change
  

• Compiler forbids null assignment:

  origin = null; // Compile-time error
  

• Also run-time check:

  Point![] path = ...;
  Object[] objs = path;
  objs[0] = null; // NullPointerException
  

• Will come to all types, not just value types: https://openjdk.org/jeps/8303099

Strict Initialization

• Local variables are always explicitly initialized (definite assignment)
• What about non-null fields, array elements?
• Primitives initialized with zero bits
• Not appropriate for all values, ex. LocalDate!
• Null-restricted fields must be strictly initialized (https://openjdk.org/jeps/8350458)
• Instance field: In constructor before call to super(...), or with initializer expression, or assigned in object initializer
• Static field: With initializer expression, or assigned in static initializer
• Array element: Provide initial value

  String![] labels;
  labels = new String![]{ "x", "y", "z" };
  labels = new String![100]{ "" }; // strawman syntax
  labels = new String![100]{ i -> "x"+i }; // strawman syntax
  

• The default value (zero bits) can never be observed!
• With JEP 482, field assignment before super possible for arbitrary classes

Trying Phase 2 Features

• Current Valhalla build supports phase 1 syntax (value modifier)
• Non-null ! will come in phase 2
• Need annotations in jdk.internal.vm.annotation package for phase 2 features
• @NullRestricted on a field (instead of !)
• @Strict on a field that is strictly initialized
• @LooselyConsistentValue to allow tearing
• jdk.internal.value.ValueClass lets you construct null-restricted arrays
• To access internals:

  javac --add-exports java.base/jdk.internal.vm.annotation=ALL-UNNAMED \
    --add-exports java.base/jdk.internal.value=ALL-UNNAMED ...
  java --add-exports java.base/jdk.internal.value=ALL-UNNAMED ...
  

• Special flags

  -XX:-UseFieldFlattening q-XX:-UseArrayFlattening -XX:-UseNullableValueFlattening
  

• Examples at https://github.com/openjdk/valhalla/blob/lworld/test/jdk/valhalla/valuetypes/

Atomic Updates

• References, primitive types ≤ 32 bits are updated atomically
• Longer values may tear
• A thread may read/write half-updated value
• Tearing more likely for longer flattened values
• Must opt in to allow tearing: (Syntax may change)

  value record Point(double x, double y)
     implements LooselyConsistentValue {}
  

  

• Then users of the class are on the hook: thread confinement, volatile, locks
• Observing tearing:

  time java --add-exports java.base/jdk.internal.value=ALL-UNNAMED --enable-preview  withtearing.Main
  Point[x=7.0, y=6.0]
  Point[x=13.0, y=14.0]
  ...
  real    0m0.367s
  
  time java --add-exports java.base/jdk.internal.value=ALL-UNNAMED --enable-preview notearing.Main
  real    0m27.675s
  

Memory Consumption

• Sleep after allocating value objects/arrays:

  Point[] path = (Point[]) ValueClass.newNullRestrictedNonAtomicArray(Point.class, NPOINTS, new Point(0, 0));
  for (int i = 1; i < path.length; i++) {
     path[i] = path[i - 1].transform();
  }
  IO.println(path[path.length - 1]);
  Thread.sleep(60_000);
  

Value type must have single field or be loosely consistent

• Observing flattening:

  javac --add-exports java.base/jdk.internal.vm.annotation=ALL-UNNAMED \
      --add-exports java.base/jdk.internal.value=ALL-UNNAMED --enable-preview --source 27 \
      withflattening/Points.java
  java --add-exports java.base/jdk.internal.value=ALL-UNNAMED --enable-preview withflattening.Points
  

  Run jcmd:

  jcmd withflattening.Points GC.class_histogram | head
  

• Flattened array with 200_000_000 double 🎉

  num     #instances         #bytes  class name (module)
  -------------------------------------------------------
     1:             1     1600000016  [Lwithflattening.Point;
  

• Without flattening:

   num     #instances         #bytes  class name (module)
  -------------------------------------------------------
     1:     100000000     3200000000  noflattening.Point
     2:             1      400000016  [Lwithvalhalla.Point; 
  

A Valhalla Puzzler

• Small change to the previous example:

  value record Point(Short x, Short y) {
      public Point transform() { return new Point((short)(y + 2), (short)(1 - x));    }
  }
  

• As before, an array of 100_000_000 non-nullable Point instances

  private static final Point[] path
      = (Point[]) ValueClass.newNullRestrictedNonAtomicArray(
          Point.class, NPOINTS, new Point((short) 0, (short) 0));
  

• GC.class_histogram:

     1:             1      800000016  [Lmoreflattening.Point;
     2:          8943         399208  [B (java.base@27-internal)
  

• Is the array flattened?
  • Yes!
  • Otherwise it would be an array of references, of size 400000016
  • And there would be 100000000 instances of moreflattening.Point
• Why 800000016? Shouldn't it be half as much? 2 short = 4 bytes.
  • It was Short, not short
  • There is a nullness bit in each instance of Short, making it 4 bytes
• If we change Short to Integer, will the array be flat? Of size 1600000016?
  • The Java/JVM spec are silent on this
  • You need to observe
  • In this presentation, you learned how

Further Reading/Viewing

• https://openjdk.org/projects/valhalla/
• JEP 401: Value Classes and Objects (Preview)
• JEP 402: Enhanced Primitive Boxing (Preview)
• JEP/Issue 8316779: Null-Restricted Value Class Types (Preview), with more info in Issue 8317765
• JEP 8350458 Strict Field Initialization in the JVM (Preview)
• JEP 218: Generics over Primitive Types ← created 2014-06-06!
• JEP 169: Larval State for Value Objects ← created 2012-10-22!
• JEP/Issue 8261529 (closed): Universal Generics
• https://github.com/forax/intellij-conf-2025
• ▶️ Brian Goetz JFokus 2025
• ▶️ Frederic Parain JVMLS 2025
• ▶️ Remi Forax, Clément de Tast Devoxx Belgium 2025

Conclusion

• After more than ten years of prototyping, value types will come to a JVM near you real soon now
• Some workloads will see significant performance improvements
• Primitive types will be approximated by null-restricted wrappers
• Conversion/overloading rules will get (even more) complex, but most programmers won’t need to care
• Generics? Still a way to go before List<int> is backed by an int[]
• When value types come, benchmark to see if they are for you
• You have now learned to see how to observe them:
  • Observe memory with flight recorder, jcmd
  • Observe VM optimizations with JITWatch
  • Benchmark with JMH
  • Tearing
• 🤔 🙋‍♀️ Questions?