We’re happy to announce GraalVM 25.5!

This release brings new compiler optimizations, developer experience and observability improvements for Native Image, and updates across the GraalVM language ecosystem. Let’s take a closer look!

Introducing Pyronaut: high-performance applications powered by GraalPy 🔥

GraalPy is enabling new ways to build Python applications. Pyronaut, a new framework from the Micronaut project, is one of them. It combines GraalPy with Micronaut’s application model to bring integrated data access, validation, and observability to Python services. Python type hints and decorators define the application, while build-time processing checks its wiring, configuration, and database queries before startup. This catches many issues before the first request and reduces the amount of infrastructure teams need to assemble.

The GraalVM stack powers both execution and integration. GraalPy runs the Python code, the Graal JIT optimizes frequently executed code, and Micronaut provides a non-blocking Netty-based HTTP runtime and access to its broader ecosystem. Python applications can use Micronaut features and JVM libraries directly, while retaining familiar Python syntax, async/await, and tools such as pytest.

Pyronaut applications can run as JVM applications for peak performance, use a reusable Crema native base for faster startup and lower memory use without rebuilding a native executable after every change, or be compiled as native executables. See the Pyronaut website for examples and steps to get started.

Even higher performance 🚀

GraalVM 25.5 adds several new compiler optimizations, many of them focused on loops. Aggressive partial unrolling and simulation-based loop peeling give the compiler more opportunities to optimize repeated work. New loop transformations can also break up long-running loops to reduce safepoint overhead and reshape loops for further optimization. Improvements to range checks, memory reads and writes, and exact arithmetic can further reduce the work performed inside eligible loops while preserving application behavior.

Beyond loops, the compiler can now eliminate more locking, including nested locking of the same object and locks across simple control flow. It can also share equivalent code from converging branches, which may reduce the size of generated code. These optimizations are enabled by default; see the release notes for the full list and corresponding options.

We expect these optimizations to particularly benefit applications that spend significant time in loops, such as those processing arrays, performing calculations, transforming data, or doing LLM inference on the CPU. Workloads with frequent synchronization or many similar control-flow branches may also see lower overhead or smaller generated code.

Even better runtime visibility 🔎

JDK diagnostic tools such as jstack, jinfo, jps, and jstat can now run on Crema to inspect other JVM processes. On Linux and macOS, native executables built with --enable-monitoring=jvmstat can also read file-backed JVMStat performance data exposed by other HotSpot and Native Image processes.

Native Image build and runtime updates 🤖

There are a few other useful practical changes:

• Clearer option errors. An unrecognized Native Image option beginning with - or -- now fails instead of being treated as a main class or output filename. If you intentionally want an output name beginning with a dash, pass it with -o, for example native-image -jar hello.jar -o --my-image, or prefix the positional name with ./.
• Bundle format 2.0. Bundles now record explicit path root kinds, build argument groups with their source platform, and markers for unavailable inputs. Older bundle formats remain readable.

WebAssembly in Oracle AI Database, powered by GraalVM 🚀

Oracle AI Database 23.26.4 adds support for WebAssembly modules in Multilingual Engine (MLE), the GraalVM-powered runtime for executing JavaScript inside the database. Developers can now store suitable Wasm binaries as MLE modules, load their JavaScript bindings, and call them as part of database logic.

This can be useful when an application needs to reuse an existing Wasm library directly where its data lives — for example, for data transformation, validation, or specialized processing — without moving the work to a separate service.

Community Updates 🤝

Every autumn brings one of our favorite annual events — GraalVM Community Summit. This year, we welcomed almost 70 committers, partners, and vendors representing companies such as Amazon, Apple, BellSoft, Broadcom, Elide, Google, HEBI Robotics, IBM, JetBrains, Netflix, Red Hat, Saxonica, and others. We spent two days discussing new features and future plans, and now are more energized than ever to make GraalVM even more useful for developers around the world 🙂

Conclusion

We’d like to take this opportunity to thank our amazing contributors and community for all the feedback, suggestions, and contributions that went into this release.

If you have feedback for this release or suggestions for features that you would like to see in future releases, please share them with us on Slack, GitHub, or LinkedIn.

Now go ahead and try the new GraalVM! 🚀

— the GraalVM team

GraalVM 25.5 is here! 🎉 was originally published in graalvm on Medium, where people are continuing the conversation by highlighting and responding to this story.

Previously, in the “Escaping the Giant Switch” episode, we learned how to break one enormous interpreter compilation unit into many independently compiled bytecode handlers.

This left us with an appealing hypothesis: if we can find the locally optimal assembly for each handler, putting those handlers together should give us a globally optimal interpreter.

We put that hypothesis to the test with the Crema interpreter, with one constraint: its Java source code had to stay maintainable.

As compiler engineers, we occasionally entertain a slightly arrogant belief: programmers should write straightforward Java, and our extremely smart compiler should handle the rest.

But when the emitted assembly falls short, who should change?

Should the compiler learn a more general optimization, or should the interpreter expose a fact that only it knows?

Act I: The Expandables

Let us start with iconst_0, one of the simplest Java bytecodes. It pushes the integer zero onto the operand stack.

For this example, we need only a compact model of the interpreter frame and stack state:

class Frame {
    /* Raw primitive values in local-variable and operand-stack slots. */
    final long[]   prims;
    /* Object references in local-variable and operand-stack slots. */
    final Object[] refs;
    /* Bytecode of the method being interpreted. */
    final byte[]   code;
}

class Stack {
    /* Next free operand-stack slot in Frame.prims/refs. */
    int top;
}

static int iconst0Handler(int bci, Frame frame, Stack stack) {
    int slot = stack.top;
    frame.prims[slot] = 0;
    stack.top = slot + 1;
    return bci + 1;
}

Here the bci parameter is the bytecode index, the byte offset of the current instruction within the method’s bytecode array.

When frame and stack cross the handler boundary as ordinary arguments, the relevant fast path assembly is:

    ; regBCI:   incoming bci
    ; regFrame: incoming frame
    ; regStack: incoming stack
    mov     regPrims, QWORD PTR [regFrame + OFFSET_prims]              ; load frame.prims
▶   mov     regTop32, DWORD PTR [regStack + OFFSET_top]                ; load stack.top
    test    regPrims, regPrims                                         ; is prims null?
    je      null_prims
    cmp     regTop32, DWORD PTR [regPrims + OFFSET_length]             ; is top out of bounds?
    jae     out_of_bounds
    mov     QWORD PTR [regPrims + regTop * 8 + OFFSET_arrayStart], 0   ; prims[slot] = 0
    inc     regTop32                                                   ; advance the stack top
▶   mov     DWORD PTR [regStack + OFFSET_top], regTop32                ; write back stack.top
    inc     regBCI32                                                   ; advance to the next bytecode
    ret
    ; Here and below, reg*32 denotes the lower 32 bits of the corresponding register.

For a bytecode that merely pushes zero, this is quite an entourage. Updating stack.top, for example, requires loading the field into a register, incrementing it, and storing it back.

In the previous article, we taught objects to cross compilation boundaries in pieces, while keeping the handler’s Java signature intact. We call this argument expansion, and distinguish two forms according to whether the original object also crosses the boundary.

With virtual expansion, the fields travel independently, without the original object reference. The generated stub reconstructs the object around those values and calls the original handler; after inlining, escape analysis can eliminate the reconstructed object.

With materialized expansion, the original object reference travels alongside selected fields. The handler receives those fields directly while retaining access to the backing object and its other fields.

For Frame, we choose materialized expansion and recruit prims , refs, and code as the expandables. For Stack, we choose virtual expansion. It sends top to join the expandables but stays behind itself.
Together, these choices change the handler’s boundary tuple from <bci, frame, stack> to <bci, frame, frame.prims, frame.refs, frame.code, stack.top>.

The tuple grew. The assembly shrank.

With the specialized calling convention, these values arrive in the registers where the handler needs them:

    ; regBCI:   incoming bci
    ; regFrame: incoming frame
    ; regPrims: incoming frame.prims
    ; regRefs:  incoming frame.refs
    ; regCode:  incoming frame.code
    ; regTop:   incoming stack.top
▶   test    regPrims, regPrims                                         ; is prims null?
▶   je      null_prims
    cmp     regTop32, DWORD PTR [regPrims + OFFSET_length]             ; is top out of bounds?
    jae     out_of_bounds
    mov     regSlot32, regTop32                                        ; zero-extend top into regSlot
    mov     QWORD PTR [regPrims + regSlot * 8 + OFFSET_arrayStart], 0  ; prims[slot] = 0
    inc     regTop32                                                   ; advance the stack top
    inc     regBCI32                                                   ; advance to the next bytecode
    ; Threaded dispatch replaces the return with a jump to the next handler
    jmp     tail_call_target(regCode, regBCI)

stack.top now arrives in the lower 32 bits of regTop, and its updated value stays there for the next handler.

The field traffic is now gone, but the null check and bounds check are still there.

Native Image’s global data-flow analysis can prove some references non-null. However, when that proof is unavailable, the compiler must retain the null check.

Fortunately, argument expansion lets us specify non-nullness as part of the handler interface. This contract applies both to direct reference arguments such as frame and to expanded reference fields such as frame.prims.
In Graal terminology, the parameter receives a non-null stamp, which describes the values that parameter can hold. The handler compilation can use that stamp to eliminate the internal null check.

The check still has to happen. Just not in every handler. The compiler inserts null checks before handler calls from the dispatch loop and before threaded tail calls. For a field such as Frame.prims, which is final, the outgoing expanded argument is still the same non-null reference. The compiler can therefore fold away the null check before the outgoing threaded tail call too.

With argument expansion and the non-null contract, the relevant threaded-handler assembly is:

    ; regBCI:   incoming bci
    ; regFrame: incoming frame       (non-null)
    ; regPrims: incoming frame.prims (non-null)
    ; regRefs:  incoming frame.refs  (non-null)
    ; regCode:  incoming frame.code  (non-null)
    ; regTop:   incoming stack.top
▶   cmp     regTop32, DWORD PTR [regPrims + OFFSET_length]             ; is top out of bounds?
▶   jae     out_of_bounds
    mov     regSlot32, regTop32                                        ; zero-extend top into regSlot
    mov     QWORD PTR [regPrims + regSlot * 8 + OFFSET_arrayStart], 0  ; prims[slot] = 0
    inc     regTop32                                                   ; advance the stack top
    inc     regBCI32                                                   ; advance to the next bytecode
    jmp     tail_call_target(regCode, regBCI)

For these unchanged references, argument expansion and the non-null contract effectively hoist the checks out of the threaded handler chain.

Less assembly. Same Java.

So far, the division of labor works.

But what about the bounds check?

Act II: Handler, Compiler, Verifier, Witness

The comparison between slot and prims.length is there for a reason. Java requires lastore to throw an ArrayIndexOutOfBoundsException when the index is outside the array bounds.

That requirement comes from the host Java code implementing the interpreter; the guest instruction iconst_0 merely pushes zero and prescribes no such exception. An out-of-bounds access here would mean an interpreter invariant had been broken, but unless the compiler can prove that slot is valid, the check stays.

Keeping that check costs more than the comparison alone. For instance, the cold exception path may keep values alive on the fast path, increasing register pressure and potentially causing spills.

So how can the compiler prove that slot is a valid index and avoid this cost?

If slot is constant and the array length is known, the proof can be immediate; if, in a counted loop, range analysis proves that every value of slot stays within the array, the check can be eliminated; if an earlier guard established 0 <= slot && slot < prims.length, the compiler can reuse it for every access it dominates.

All of these optimizations require the compiler to derive the proof from information in its graph.

Our tiny handler, however, is compiled as a standalone unit. Its graph receives stack.top and frame.prims as independent inputs, with no proof that the resulting slot is a valid index into the array.

Fortunately, the Java bytecode verifier can serve as a witness outside that graph.

Before the JVM executes a method’s bytecode, the bytecode verifier establishes a valid frame shape at every reachable bytecode index. Among other properties, it proves that every operand-stack operation stays within the max_stack recorded in the method’s class-file Code attribute. As long as an interpreter allocates operand-stack storage for that same max_stack and implements the verified operations faithfully, every operand-stack access is within the allocated storage.

In that sense, verification plays the role of a guard that dominates the entire interpretation. But it lives outside the handler’s compilation unit, so the compiler cannot reuse it as a dominating guard in the handler graph.

Could we use the same stamp-based contract that previously removed the null checks?

Just as a stamp can express non-nullness, it can also express a constant integer range such as [0, 63]. However, the required range is [0, prims.length), whose upper bound is a runtime value rather than a compiler constant. The stamp system cannot express this relationship between two runtime values.

For an ordinary Java array access, without a proof in the graph, the compiler must retain precisely the comparison and branch we want to remove.

Alternatively, we can make the verifier-established invariant an implicit assumption in the interpreter source, replacing the checked array write with an Unsafe-backed access:

static int iconst0Handler(int bci, Frame frame, Stack stack) {
    int slot = stack.top;
    UNSAFE.putLong(frame.prims, slot * 8L + OFFSET_arrayStart, 0);
    stack.top = slot + 1;
    return bci + 1;
}

The bounds check no longer enters the handler’s graph, and the relevant assembly becomes:

    ; regBCI:   incoming bci
    ; regFrame: incoming frame       (non-null)
    ; regPrims: incoming frame.prims (non-null)
    ; regRefs:  incoming frame.refs  (non-null)
    ; regCode:  incoming frame.code  (non-null)
    ; regTop:   incoming stack.top
▶   movsxd  regSlot, regTop32                                          ; sign-extend top into regSlot
    mov     QWORD PTR [regPrims + regSlot * 8 + OFFSET_arrayStart], 0  ; prims[slot] = 0
    inc     regTop32                                                   ; advance the stack top
    inc     regBCI32                                                   ; advance to the next bytecode
    jmp     tail_call_target(regCode, regBCI)

The array-length load, conditional branch, and cold exception edge have all disappeared. Correctness now rests on verification, frame allocation, and the interpreter preserving the verified stack discipline.

One Move Too Many

The bounds check is gone. But the zero-extension has quietly become a sign-extension.

Why?

Consider an input stack.top = -1, giving us slot = -1. Sign-extension preserves that value as 0xFFFFFFFF_FFFFFFFF, while zero-extension produces 0x00000000_FFFFFFFF. Using the latter in the Unsafe access would compute the wrong address, potentially causing a segmentation fault or memory corruption.

Of course, this input cannot occur in a correctly implemented interpreter executing verified bytecode. But that guarantee remains implicit in the source, so the compiler cannot use it to rule out negative inputs and must preserve Java’s signed conversion.

Before the switch to Unsafe, the compiler had to insert a bounds check.
Once that check passed, it knew that slot was non-negative at the array access. For a non-negative int, sign-extension and zero-extension produce the same 64-bit value, so it could replace the former with the latter. On processors that support move elimination, the resulting register move can be handled during register renaming, avoiding an execution step that sign-extension would require.

Zero-extension also gives the compiler an opportunity to eliminate the move entirely — a small prize, but one that can be significant in benchmarks such as SPECjvm. On x64, writing a 32-bit register also clears its upper 32 bits. If the compiler knows that the instruction that produced slot already did this, it may use that register directly as the address index.

Then why couldn’t the compiler eliminate the zero-extending move in our expanded handler before the switch to Unsafe?

Our stack.top arrives as an expanded parameter, so its producing instruction is outside this compilation unit. The calling convention promises an int in the lower 32 bits of regTop; it does not promise that the upper 32 bits are zero. Consider another input, stack.top = 1. The incoming register could contain 0x00000001_00000001, with the correct int value in its lower half. Using the entire register as an address index would include those non-zero upper bits, potentially causing a segmentation fault or memory corruption.

Proving that stack.top already arrives in a register containing its correctly extended, full-width value would require reasoning across compilation boundaries. We can avoid that proof by making the full-width value part of the handler interface. Changing the index’s representation to long preserves the invariants established by verification. Plus, with Unsafe, we are no longer constrained by Java’s int array indices, since the access takes a long byte offset.

We therefore changed both stack.top and bci to long, so each arrives as a 64-bit index ready for addressing. Here too, the verifier testifies that branch targets stay within the bytecode array. Neither index needs widening in each handler.

Our running example now becomes:

class Stack {
    long top;
}

static long iconst0Handler(long bci, Frame frame, Stack stack) {
    long slot = stack.top;
    UNSAFE.putLong(frame.prims, slot * 8L + OFFSET_arrayStart, 0);
    stack.top = slot + 1;
    return bci + 1;
}

The incoming stack top can serve directly as the address index:

    ; regBCI:   incoming bci         (long)
    ; regFrame: incoming frame       (non-null)
    ; regPrims: incoming frame.prims (non-null)
    ; regRefs:  incoming frame.refs  (non-null)
    ; regCode:  incoming frame.code  (non-null)
    ; regTop:   incoming stack.top   (long)
    mov     QWORD PTR [regPrims + regTop * 8 + OFFSET_arrayStart], 0
    inc     regTop
    inc     regBCI
    jmp     tail_call_target(regCode, regBCI)  ; long bci also avoids widening in the unshown dispatch code

Store zero. Advance the indices. Dispatch.

That is more like it.

Supplementary Testimony

The verifier establishes more than stack capacity.
For an interpreter, those guarantees fall into two useful categories:

• Access bounds: operand-stack and local-variable accesses stay within the storage allocated from max_stack and max_locals; bytecode operands form complete instructions; branch and exception-handler targets name valid instruction boundaries; and constant-pool indices refer to valid entries.
• Type safety: every instruction consumes and produces compatible verification types; stack-manipulation forms are legal; field accesses, invocations, and returns agree with their descriptors; and uninitialized references obey the constructor rules.

The type-safety proofs are normally implicit in the handler implementation. For example, an iadd handler expects two integers on the operand stack without checking their runtime types.

Other type guarantees belong to a particular bytecode site rather than to every execution of an instruction. How can we make those facts useful to a shared handler?

Consider baload, which operates on either a byte[] or a boolean[].
Its shared handler contains a type check to distinguish the two array kinds at run time. At a given BCI, however, verification fixes the non-null array operand’s type as either byte[] or boolean[]; it cannot admit both at the same site. Different baload sites may have different array types, so this knowledge cannot be baked into a single shared handler. The guest-array null and bounds checks are still required.

We could use the verifier’s result to rewrite baload at that BCI to a byte[]- or boolean[]-specific opcode before execution begins.

Alternatively, we can record this site-specific information through runtime quickening.

On the first execution with a non-null array, the generic handler observes its type and rewrites that BCI to select one of two shared specialized handlers. A single runtime observation would not normally justify permanent specialization; the verifier’s BCI-specific guarantee makes it sufficient here. Subsequent executions use the specialized handler without repeating the type check. The specialized opcode carries the site’s type information into handler selection.

The same pattern applies when the initial execution establishes information that does not come from verification. For a field access, the original handler resolves the field, performs the opcode-specific access checks, and then quickens the opcode. The quickened handler retrieves the cached resolved entry without repeating resolution or those access checks.

To summarize, the compiler must generate correct code for every input its interface permits, while the interpreter’s external guarantees rule out some of those inputs. When the compiler cannot see those guarantees, we can still use them to choose a different implementation.

We have done so through unchecked accesses, wider parameters, and specialized opcodes, putting external knowledge to work without teaching the compiler its original proofs.

But how far should we push this?

Act III: How to Train Your Compiler

Let us return to the iconst_0 example. Can we make its assembly even simpler?

Suppose we carried the address of the next primitive element instead of its logical slot. In C-like code, initializing the pointer and pushing zero would look something like this:

int64_t *stack = &frame.prims[top];  // Initialize from the logical top outside of the handlers
...
*stack = 0;                          // Push zero
stack++;                             // Advance by eight bytes

With the pointer carried in regStack across threaded tail calls, pushing zero and advancing it could compile to:

    mov     QWORD PTR [regStack], 0
    add     regStack, 8

The simpler addressing mode does not necessarily improve performance.
On Intel Skylake, both the original indexed store and this direct-address store execute as two micro-operations. The direct-address form can use an additional store-address port, which may help under contention, but does not guarantee a cycle saving.

The interpreter’s Java implementation, meanwhile, becomes more cumbersome. The stack top no longer names a logical slot. To address both primitive and reference arrays directly, we now have to maintain two pointers, advancing each according to its array’s element size. We must also keep these pointers into the managed heap valid across garbage collection and safepoints.

Making the source so much harder to read is a poor trade when we cannot even establish a performance gain. The choice becomes less clear when keeping the source tidy leaves avoidable work in the generated code.

The Pursuit of Constants

Consider putfield, whose handler branches according to the kind of field it stores into. An int occupies one stack slot, while a long occupies two, so their values start at stack.top — 1 and stack.top-2, respectively.
In either case, the receiver sits in the preceding slot.

Using our Frame and Stack abstraction, a natural implementation is to share the slot calculations and receiver lookup before branching on the field kind:

static long putfieldHandler(long bci, Frame frame, Stack stack) {
    JavaField field           = resolveField(frame, bci);
    JavaKind  kind            = field.kind();
    long      valueSlot       = stack.top - kind.slotCount();
    long      receiverSlot    = valueSlot - 1;
    Object    receiver        = UNSAFE.getReference(frame.refs, receiverSlot * OFFSET_referenceScale + OFFSET_arrayStart);
    Object    nonNullReceiver = nullCheck(receiver);
    long      offset          = field.offset();
    boolean   isVolatile      = field.isVolatile();

    switch (kind) {
        case Int -> {
            // OFFSET_endian is 4 on big-endian targets, otherwise 0.
            int value = UNSAFE.getInt(frame.prims, valueSlot * 8L + OFFSET_arrayStart + OFFSET_endian);
            if (isVolatile) {
                UNSAFE.putIntVolatile(nonNullReceiver, offset, value);
            } else {
                UNSAFE.putInt(nonNullReceiver, offset, value);
            }
        }
        case Long -> {
            long value = UNSAFE.getLong(frame.prims, valueSlot * 8L + OFFSET_arrayStart);
            if (isVolatile) {
                UNSAFE.putLongVolatile(nonNullReceiver, offset, value);
            } else {
                UNSAFE.putLong(nonNullReceiver, offset, value);
            }
        }
        // Other valid field kinds omitted.
        default -> throw shouldNotReachHere();
    }
    UNSAFE.putReference(frame.refs, receiverSlot * OFFSET_referenceScale + OFFSET_arrayStart, null);
    stack.top = receiverSlot;
    return bci + 3;
}

The relevant x64 assembly snippet leading into the switch is the following.

    ; regBCI:   incoming bci         (long)
    ; regFrame: incoming frame       (non-null)
    ; regPrims: incoming frame.prims (non-null)
    ; regRefs:  incoming frame.refs  (non-null)
    ; regCode:  incoming frame.code  (non-null)
    ; regTop:   incoming stack.top   (long)
    ; regKindObject holds the decompressed JavaKind reference; setup and null checks omitted.
    ; ... receiver decompression omitted ...
▶   mov     QWORD PTR [rsp + 0x28], regFieldObject  ; spill decompressed field reference
    movsxd  regSlots,      DWORD PTR [regKindObject + OFFSET_slotCount]
    mov     regValueSlot, regTop
    sub     regValueSlot, regSlots          ; valueSlot = top - kind.slotCount()
    mov     regReceiver32, DWORD PTR [regRefs + regValueSlot * 4 + OFFSET_arrayStart - 4]
    mov     regReceiverSlot, regValueSlot
    dec     regReceiverSlot                 ; receiverSlot = valueSlot - 1
    test    regReceiver32, regReceiver32    ; is receiver null?
    je      null_receiver

▶   mov     QWORD PTR [rsp + 0x60], regTop          ; spill stack top
    ; ... field offset/modifier loads omitted ...
    mov     regKind32,     DWORD PTR [regKindObject + OFFSET_ordinal]
    ; ... ordinal bounds check omitted ...
▶   mov     QWORD PTR [rsp + 0x10], regKindObject   ; spill decompressed JavaKind reference
    ; ... ordinal jump table, typed stores, and threaded dispatch omitted ...

At first glance, that is exactly what we asked for. It loads the slot count from JavaKind, then computes valueSlot and receiverSlot before the switch. The receiver load folds the subtraction into its address, but receiverSlot is still computed separately for the later update to stack.top.

Yet once we enter a switch arm, the slot count is fixed, giving us an opportunity for constant folding. In the int case, for example, replacing the slot count with one would simplify valueSlot to stack.top-1 and receiverSlot to stack.top-2. The memory accesses could then absorb those constant offsets into their address displacements. For the receiver, that gives DWORD PTR [regRefs + regTop * 4 + OFFSET_arrayStart-8]. The stack update could subtract two directly from top at the end.

That suggests a manual rewrite. Move the shared setup into the branches and specialize it for each kind:

static long putfieldHandler(long bci, Frame frame, Stack stack) {
    JavaField field = resolveField(frame, bci);
    JavaKind kind = field.kind();
    // Verification and linking guarantee a valid field kind.
    switch (kind) {
        case Int -> {
            long receiverSlot = stack.top - 2;
            long valueSlot = stack.top - 1;
            Object receiver = UNSAFE.getReference(frame.refs, receiverSlot * OFFSET_referenceScale + OFFSET_arrayStart);
            Object nonNullReceiver = nullCheck(receiver);
            int value = UNSAFE.getInt(frame.prims, valueSlot * 8L + OFFSET_arrayStart + OFFSET_endian);
            if (field.isVolatile()) {
                UNSAFE.putIntVolatile(nonNullReceiver, field.offset(), value);
            } else {
                UNSAFE.putInt(nonNullReceiver, field.offset(), value);
            }
            UNSAFE.putReference(frame.refs, receiverSlot * OFFSET_referenceScale + OFFSET_arrayStart, null);
            stack.top = receiverSlot;
        }
        case Long -> {
            long receiverSlot = stack.top - 3;
            long valueSlot = stack.top - 2;
            Object receiver = UNSAFE.getReference(frame.refs, receiverSlot * OFFSET_referenceScale + OFFSET_arrayStart);
            Object nonNullReceiver = nullCheck(receiver);
            long value = UNSAFE.getLong(frame.prims, valueSlot * 8L + OFFSET_arrayStart);
            if (field.isVolatile()) {
                UNSAFE.putLongVolatile(nonNullReceiver, field.offset(), value);
            } else {
                UNSAFE.putLong(nonNullReceiver, field.offset(), value);
            }
            UNSAFE.putReference(frame.refs, receiverSlot * OFFSET_referenceScale + OFFSET_arrayStart, null);
            stack.top = receiverSlot;
        }
        // Other valid field kinds omitted.
        default -> throw shouldNotReachHere();
    }
    return bci + 3;
}

For the int case, the resulting addresses are:

    ; Int arm after duplicating the setup; other instructions omitted.
    ; Same incoming registers; regTop still holds the incoming stack.top.
    ; OFFSET_arrayStart = 8 and reference scale = 4 in this build.
    mov     regReceiver32, DWORD PTR [regRefs + regTop * 4]  ; disp = 8 - 4 * 2
    ; ... receiver decompression omitted ...
    test    regReceiver32, regReceiver32                   ; is receiver null?
    je      null_receiver_int
    mov     regValue32,    DWORD PTR [regPrims + regTop * 8] ; disp = 8 - 8 * 1
    ; ... stack update, volatility test, and field store omitted ...

The other arms fold their constant slot offsets into the addresses in the same way.

More Java. Less assembly.

But why can’t the compiler do this for us?

Graal can fold a final field read when the object containing the field is a known constant. But javac lowers an enum switch to an integer switch derived from ordinal(), typically through a synthetic mapping array. Entering the int case constrains this integer; it does not turn kind into the constant JavaKind.Int in the compiler graph. The slotCount read used to compute valueSlot therefore still has a dynamic receiver.

Teaching the compiler to map an ordinal back to its JavaKind instance could enable branch-local constant folding. That would require trusting the enum’s canonical-instance invariant, much as final-field folding trusts that a field’s value will not change.

HotSpot’s C2 compiler does not trust arbitrary instance final fields for constant folding by default, though it makes exceptions for certain classes. Its experimental -XX:+TrustFinalNonStaticFields option broadens that trust. Graal uses a different policy.

Even if the compiler could establish the enum identity in each branch, that alone would solve only half of our problem. It could specialize valueSlot within each branch, but the shared receiver access would still use the dynamic slot count before the switch. Eliminating that load would require duplicating the receiver access and null check into the branches as well.
The default branch would need to preserve the original calculation and null check before throwing its own exception. This is possible, but it requires teaching the compiler when that duplication is worth the extra code.

Let us leave that as a feature request for the compiler.

A Little Too Helpful

While we admire the result of constant folding, the compiler may be undoing some of our careful duplication. For instance, each branch calls field.offset(), which reads the same field offset from the resolved metadata object. Writing that call inside each arm does not necessarily keep the load there.

Graal can turn an eligible field load into a floating read: a load whose position is determined by its dependencies rather than fixed to a point in the control flow. Equivalent reads with matching dependencies can then become one shared node through global value numbering.

As long as the value remains shared, the scheduler must place it where it is available to all its uses. When those uses lie in different switch arms, this means placing it in a common dominator before the switch, provided its dependencies allow it. Sharing the load saves instruction bytes, but its result now has to stay live across the dispatch. In the duplicated handler, the field offset and modifier reads have moved before the switch:

    ; Before kind dispatch; regField holds the compressed field reference.
    ; save values before reusing their registers.
▶   mov     QWORD PTR [rsp + 0x20], regKindObject   ; spill decompressed JavaKind reference
▶   mov     DWORD PTR [rsp + 0x1c], regKindRef32    ; spill compressed JavaKind reference
▶   mov     QWORD PTR [rsp + 0x28], regFieldObject  ; spill decompressed field reference
▶   mov     QWORD PTR [rsp + 0x30], regFrame        ; spill frame reference
    movsxd  regOffset,  DWORD PTR [regHeapBase + regField * 8 + OFFSET_fieldOffset]
    mov     regFlags32, 0x50df
    and     regFlags16, WORD PTR [regHeapBase + regField * 8 + OFFSET_modifiers]
    movzx   regFlags32, regFlags16
    mov     regValueSlot, regTop
    dec     regValueSlot                   ; top - 1
    lea     regReceiverSlot, [regTop - 2]  ; shared by the one-slot arms
    lea     regNextBCI, [regBCI + 3]
    ; ... ordinal range check and jump-table dispatch ...

The same can happen to arithmetic. Across the one-slot cases — boolean, byte, char, and others — the same stack.top-2 calculation appears for the outgoing stack top. If these calculations become one shared node, it must execute before the switch, even though not every arm needs the result.

Graal’s partial-redundancy-aware scheduler can undo this sharing by duplicating a computation into the branches that need it. Its general heuristic favors splitting when doing so reduces execution frequency. The stack.top-3 calculation shared by the long and double arms illustrates this: the scheduler splits it back into those arms, avoiding the calculation on the more frequent one-slot paths. But the shared stack.top-2 calculation serves most of the execution, so splitting it offers too little frequency saving — even though it would shorten live ranges.

Keeping the computation shared is a reasonable choice until registers become scarce. The jump-table dispatch generated from the switch needs its selector and a register for the target address, alongside the interpreter state carried to the next handler. Hoisted loads and slot calculations add to that live set even though only one arm will execute. If their overlapping lifetimes exceed the available registers, the allocator must spill something, which is unfortunately the case in many handlers with complicated branching logic. The compiler’s good intentions in sharing computations then turn into extra stores and reloads.

How do we train the compiler to reduce spilling?

We can start with compiler directives. One of my favorites is GraalDirectives.opaque, which returns the same runtime value but hides it behind a distinct compiler node. Wrapping field and stack.top separately in each switch arm prevents the compiler from simply treating the resulting expressions as shared work. With each copy used only in its own arm, the scheduler can keep the dependent reads and arithmetic there.

Our int case now looks like this:

case Int -> {
    field = GraalDirectives.opaque(field);
    long top = GraalDirectives.opaque(stack.top);
    long receiverSlot = top - 2;
    long valueSlot = top - 1;
    // ... receiver check, field store, and stack update using field and these slots ...
}

It works. It’s just ugly.

Every arm now describes both the bytecode’s behavior and how we want it compiled. Worse, the desired placement depends on the compiler’s treatment of these directives, so a compiler change may send us back to rearrange the source.

We can instead teach the compiler the tradeoff directly: accept a little more generated code in exchange for shorter live ranges.

We restrict read hoisting and sharing, and teach the scheduler to favor separate copies of arithmetic in the consuming branches. The field metadata loads and slot calculations now stay inside the arms, without the source directives:

    ; No spills before the switch; dispatch omitted.

int_case:
▶   mov     QWORD PTR [rsp + 0x18], regKindObject   ; spill decompressed JavaKind reference
▶   mov     QWORD PTR [rsp + 0x20], regFieldObject  ; spill decompressed field reference
    mov     regReceiver32, DWORD PTR [regRefs + regTop * 4]
    lea     regReceiverSlot, [regTop - 2]
    test    regReceiver32, regReceiver32
    je      null_receiver_int
    ; ... value load and modifier handling omitted ...
    mov     regOffset32, DWORD PTR [regHeapBase + regField * 8 + OFFSET_fieldOffset]
    ; ... volatility check, receiver decompression, offset widening, and field store ...

The long arm computes top-3 instead. Neither arm carries the other’s stack update through the switch.

These choices deliberately work against optimizations we built for general-purpose compilation. Sharing work is usually sensible, but our tiny handlers have tightly constrained register interfaces. We therefore special-case handler stubs, putting this policy in the compiler instead of repeating it through directives in every handler.

Das Leben der Anderen

Even then, spills can remain.

The two stores inside the int arm preserve values for the null-check exception path and a later safepoint slow path, omitted from the assembly excerpt.

Neither slow path uses these values for its actual work. Why keep them alive?

At a call site — including the runtime call on a safepoint poll’s slow path — the compiler may need to describe the caller’s Java execution state for deoptimization, debugging, or runtime stack inspection. Graal records this execution state in a frame state. That can include local variables the call itself never uses, potentially keeping them alive beyond their last executable use. It can even force a reference to be decompressed solely for bookkeeping, although subsequent field accesses need only its compressed form.

In our putfield example, both slow paths retain the decompressed field and JavaKind references alongside other parameters and locals.

Keeping a value alive does not require spilling it immediately. There are enough registers for the live values just before this null check. But these references remain live alongside the temporaries needed for the field store, increasing register pressure inside the arm.

On handler fast paths, Graal’s register allocator favors spilling values with no remaining register-requiring uses when it needs to free a register. Neither decompressed reference has another executable use, making both attractive spill candidates. Here, the resulting interval assignments place the stores before the null check, so the fast path pays too.

One source-level response is to stop giving intermediate results their own locals. For putfield, we could remove the kind local and write the switch directly:

switch (field.kind()) {
    // ... same arms ...
}

The same approach becomes less pleasant in invokestatic:

static long invokeStaticHandler(long bci, Frame frame, Stack stack) {
    CallInfo callInfo = resolveCall(bci, frame);
    Object retObj = VM.dispatchCall(
            popArguments(
                    callInfo.argumentCount == 0
                            ? EMPTY_ARRAY
                            : new Object[callInfo.argumentCount],
                    frame,
                    stack,
                    callInfo),
            bci,
            frame,
            callInfo);
    // ... return handling and next BCI omitted ...
}

To avoid an intermediate local, we have crammed argument allocation, preparation, and invocation into one expression — an anti-pattern adopted to satisfy the compiler’s bookkeeping.

But our handler stubs cannot deoptimize. Unless debugging or runtime inspection requires their local values, we can discard that bookkeeping.

We therefore teach the compiler which frame-state values these stubs actually need, and prune the rest before register allocation. We retain the BCI used to report the guest’s execution position during stack walking, along with lock information. Live references needed by the GC remain tracked.

The two spill stores disappear from the int arm:

int_case:
    mov     regReceiver32, DWORD PTR [regRefs + regTop * 4]
    test    regReceiver32, regReceiver32
    je      null_receiver_int
    ; ... value load, field store, stack update, and continuation ...

Now a local variable can go back to being a name that helps us read the code.

One Spill Flew Over the Sibling’s Nest

Return to the version before frame-state pruning. The remaining mystery is why the int arm spills both references as soon as it begins.

At the null check, 11 live intervals overlap, against 12 allocatable general-purpose registers in our x64 build. Pressure rises later in the field-store sequence, where 13 intervals overlap.

Why pay for two spills on entry?

The answer starts in another arm.

Graal’s linear-scan allocator lays out basic blocks and instructions along a one-dimensional axis, then represents each value’s lifetime as ranges on that axis. Those intervals can contain gaps and be split into children with different register or stack assignments. Allocation follows this linear order, while liveness analysis and reconciliation between blocks still use the control-flow graph.

In the putfield compilation, the allocator visits the Object arm before the int arm. There, 14 live intervals compete for 12 registers. The decompressed kind and field references become spill victims, freeing registers for the remaining work. The stores appear in the blocks where that pressure rises.

But their stack assignments extend into the later int arm too. The switch still supplies both references in registers. The Object arm’s stores never execute on the int path, so data-flow resolution must insert new stores to satisfy the int arm’s inherited stack assignments. It places them at the arm’s entrance, before the null check.

The int arm has register pressure of its own, but these two stack assignments originate in its sibling. It inherits both spills — and pays for them on entry, even though it may not need to free both registers.

We therefore teach the compiler to give a sibling another chance at a register.

When a spilled interval extends into another block, the allocator checks the locations supplied by its actual predecessors. If the stack assignment does not arrive on every incoming path, it splits the interval at that block’s entrance and allocates the new child separately.

The new child prefers the register already supplied by an incoming path. This lets the arms make different choices for the same value.

That independence costs compilation time. Each split requires predecessor checks and creates another interval to allocate, which may itself be split again. Across a large method, this extra work can erode the speed that makes linear scan attractive.

Yet again, we give handler stubs special treatment. After so many amendments to the compiler’s usual rules, an uncomfortable question presents itself.

Why not write assembly?

Act IV: Everything Everywhere All at Once

Well, that is not for me to decide.

When my boss Doug Simon and the team started the Maxine VM project, the idea was Java on Java.

I never convinced them to add __asm__ to Java, so I need an excuse to convince myself.

Luckily, there is one.

Our iconst_0 and putfield examples already use a Stack object, but the handlers still access the backing arrays directly.

Let us encapsulate those accesses in the stack abstraction. Instead of:

class Stack {
    long top;
}

static long iconst0Handler(long bci, Frame frame, Stack stack) {
    long slot = stack.top;
    UNSAFE.putLong(frame.prims, slot * 8L + OFFSET_arrayStart, 0);
    stack.top = slot + 1;
    return bci + 1;
}

We can write:

class Stack {
    long top;

    void pushInt(Frame frame, int value) {
        UNSAFE.putLong(frame.prims, top * 8L + OFFSET_arrayStart, value);
        top++;
    }

    int popInt(Frame frame) {
        top--;
        return (int) UNSAFE.getLong(frame.prims, top * 8L + OFFSET_arrayStart);
    }
}

static long iconst0Handler(long bci, Frame frame, Stack stack) {
    stack.pushInt(frame, 0);
    return bci + 1;
}

Stack now provides an overlay on the frame, while virtual argument expansion keeps that overlay in the source without carrying an object into the emitted assembly.

The handler no longer needs to know where zero goes.

We can now subclass Stack and override pushInt, caching values in instance fields instead of writing them immediately to the backing array.
Again, argument expansion carries these fields between handlers in registers.

That gives us top-of-stack caching.

One Field, Many Roles

Let us return to the simplest cache from the previous article, with two primitive fields, tos1 and tos2, and a template variable tosDepth counting the cached JVM slots. We can view these fields as an extension of Frame.prims: they hold stack slots just like the array elements, except they live in registers. top marks the end of the materialized stack; the cached slots extend it. Object references remain in the backing frame, so before pushing one, we write back the cached values and reset tosDepth to zero.

The following table shows a selection of handlers, how they interpret the cached slots, and what they leave for the next handler.

The types represented by tos1 and tos2 change across handlers, but we need no runtime type tests. The bytecode verifier establishes the operand types, and the cache protocol preserves their representation. The remaining question is how to use those bits without paying for a conversion.

We declare tos1 and tos2 as long, wide enough to hold the bits of any primitive value. Reading an int through an ordinary Java cast introduces a narrowing operation into the compiler graph. Depending on how it is lowered and allocated, that operation can introduce a register move and a separate register for the narrowed value.

For an integer operand, however, our protocol already places the value in the register’s lower 32 bits. We use a compiler directive to read those bits as an int, without introducing a separate narrowing operation. The upper bits need not be zero; a 32-bit use simply does not read them. Writing an integer back into a cache field needs the matching treatment: preserve its low 32 bits without requesting Java’s signed widening to long. unpackInt ignores the upper bits; packInt leaves them unspecified. On x64, the 32-bit arithmetic already supplies the bits we need.

That leaves two more mysterious entries in the table: Preserved and Unconstrained. A preserved value must reach the next handler unchanged, but passing it through requires no knowledge of its type.
For nop(tosDepth=2), both fields have Schrödinger’s type: their bits have a meaning, but we have no reason to look. Matching incoming and outgoing ABI registers lets the allocator carry these values through without moves, provided it keeps those registers intact.

Passing the bits through is enough until we need to write them back to the frame. Then we must know how much stack space they occupy. Our current state machine avoids that ambiguity by counting slots rather than values: a fully cached long uses both cache fields, including its padding.
Caching two longs would require a state that tells us more. We will come back to this later.

An unconstrained field need not preserve even its bits. For nop(tosDepth=1), we can pass whatever bits happen to occupy the register for tos2. We express this freedom through compiler directives, allowing the allocator to reuse that register inside the handler without preserving or restoring its contents. We need not even put zero there before the next handler.

We have already complained about directives cluttering the source.
Fortunately, we can sweep this machinery under the Stack overlay’s carpet. The handler compilation knows the concrete stack implementation, so it can inline the overridden operations.

// Directive names in this illustrative example describe their intended contracts.
class CachedStack extends Stack {
    static final int NO_SLOTS_CACHED = 0;
    static final int ONE_SLOT_CACHED = 1;
    static final int TWO_SLOTS_CACHED = 2;

    long tos1;
    long tos2;
    int tosDepth = NO_SLOTS_CACHED;

    @Override
    void pushInt(Frame frame, int value) {
        switch (tosDepth) {
            case ONE_SLOT_CACHED -> {
                tos2 = GraalDirectives.packInt(value);
                tosDepth = TWO_SLOTS_CACHED;
            }
            case TWO_SLOTS_CACHED -> {
                UNSAFE.putLong(frame.prims, top * 8L + OFFSET_arrayStart, tos1);
                top++;
                tos1 = tos2;
                tos2 = GraalDirectives.packInt(value);
                // The cache stays full: 2 → 2.
            }
            default -> {
                assert tosDepth == NO_SLOTS_CACHED;
                tos1 = GraalDirectives.packInt(value);
                tosDepth = ONE_SLOT_CACHED;
            }
        }
    }

    @Override
    int popInt(Frame frame) {
        return switch (tosDepth) {
            case ONE_SLOT_CACHED -> {
                tosDepth = NO_SLOTS_CACHED;
                long result = tos1;
                tos1 = GraalDirectives.unconstrainedValue();
                yield GraalDirectives.unpackInt(result);
            }
            case TWO_SLOTS_CACHED -> {
                tosDepth = ONE_SLOT_CACHED;
                long result = tos2;
                tos2 = GraalDirectives.unconstrainedValue();
                yield GraalDirectives.unpackInt(result);
            }
            default -> {
                assert tosDepth == NO_SLOTS_CACHED;
                top--;
                yield (int) UNSAFE.getLong(frame.prims, top * 8L + OFFSET_arrayStart);
            }
        };
    }
}

The handler sees only stack operations:

static long iadd(long bci, Frame frame, Stack stack) {
    int right = stack.popInt(frame);
    int left = stack.popInt(frame);
    stack.pushInt(frame, left + right);
    return bci + 1;
}

One Handler, Many Variants

Let us manually inline the two pops and the push in iadd, keeping only the operations that affect tosDepth:

static long iadd(long bci, Frame frame, CachedStack stack) {
    // First popInt.
    switch (stack.tosDepth) {
        case ONE_SLOT_CACHED -> stack.tosDepth = NO_SLOTS_CACHED;
        case TWO_SLOTS_CACHED -> stack.tosDepth = ONE_SLOT_CACHED;
        default -> { }
    }

    // Second popInt.
    switch (stack.tosDepth) {
        case ONE_SLOT_CACHED -> stack.tosDepth = NO_SLOTS_CACHED;
        case TWO_SLOTS_CACHED -> stack.tosDepth = ONE_SLOT_CACHED;
        default -> { }
    }

    // pushInt.
    switch (stack.tosDepth) {
        case ONE_SLOT_CACHED -> stack.tosDepth = TWO_SLOTS_CACHED;
        case TWO_SLOTS_CACHED -> { }
        default -> stack.tosDepth = ONE_SLOT_CACHED;
    }
    return bci + 1;
}

The previous article introduced handler specialization: give the incoming template variable a constant value and let constant folding do its job. For iadd(tosDepth=2), each state update determines which arm of the next switch survives. The markers below trace that sequence:

static long iadd_2(long bci, Frame frame, CachedStack stack) {
    // Represents the incoming template constant, not a runtime assignment.
    stack.tosDepth = TWO_SLOTS_CACHED;

    // First popInt.
    switch (stack.tosDepth) {
        case ONE_SLOT_CACHED -> stack.tosDepth = NO_SLOTS_CACHED;
▶       case TWO_SLOTS_CACHED -> stack.tosDepth = ONE_SLOT_CACHED;
        default -> { }
    }

    // Second popInt.
    switch (stack.tosDepth) {
▶       case ONE_SLOT_CACHED -> stack.tosDepth = NO_SLOTS_CACHED;
        case TWO_SLOTS_CACHED -> stack.tosDepth = ONE_SLOT_CACHED;
        default -> { }
    }

    // pushInt.
    switch (stack.tosDepth) {
        case ONE_SLOT_CACHED -> stack.tosDepth = TWO_SLOTS_CACHED;
        case TWO_SLOTS_CACHED -> { }
▶       default -> stack.tosDepth = ONE_SLOT_CACHED;
    }
    return bci + 1;
}

Restoring the operand operations, constant folding and dead-code elimination leave:

static long iadd_2(long bci, Frame frame, CachedStack stack) {
    int right = GraalDirectives.unpackInt(stack.tos2);
    int left = GraalDirectives.unpackInt(stack.tos1);
    stack.tos1 = GraalDirectives.packInt(left + right);
    stack.tos2 = GraalDirectives.unconstrainedValue();
    stack.tosDepth = ONE_SLOT_CACHED;
    return bci + 1;
}

The corresponding assembly is compact:

    ; regBCI:   incoming bci         (long)
    ; regFrame: incoming frame       (non-null)
    ; regPrims: incoming frame.prims (non-null)
    ; regRefs:  incoming frame.refs  (non-null)
    ; regCode:  incoming frame.code  (non-null)
    ; regTop:   incoming stack.top   (long)
    ; regTos1:  incoming stack.tos1  (long)
    ; regTos2:  incoming stack.tos2  (long)
    add     regTos1_32, regTos2_32              ; Java int addition
    inc     regBCI
    jmp     tail_call_target(regCode, regBCI, ONE_SLOT_CACHED)

The same process derives iadd(tosDepth=0) and iadd(tosDepth=1), which fetch two operands or one operand from the backing frame, respectively.

The handlers describe bytecode behavior; the stack implementation supplies caching behavior wherever those operations occur.
Inlining brings them together, and constant folding derives each specialized variant. This is an aspect-oriented way to implement the optimization.

We still design the transitions in the stack abstraction, but need not calculate the outgoing tosDepth separately for every handler. The compiler fills in that column for us. That state selects the next already-specialized handler at the threaded tail call.

That only works while the compiler can determine the outgoing state on each path. Different branches may lead to different constant states, but invocation bytecodes are less cooperative: they may pop arguments in a loop whose iteration count depends on the target method. Our implementations flush the cache before that loop and finish with a known empty-cache state. Code that operates directly on the backing frame likewise needs the cached values written back first.

Flushing is less alarming than it sounds. These are the stack stores the uncached interpreter would have performed earlier; caching merely postpones them, and may eliminate some before a flush is needed.

Writing cached values back does not require allocating the overlay object. It can remain virtual, provided we do not let it escape through a call.

One Interpreter, Many Stack Implementations

Now we can change the stack implementation without rewriting the handlers. A different subclass can encode a different state machine.

Our first model spends two cache fields on one long, including its padding, because the state counts slots rather than values.
But the state could tell us more.

Let <CAT1> mean an int or float, occupying one JVM slot, and <CAT2> mean a long or double, occupying two. We then have six populated states: <CAT1>, <CAT2>, <CAT1,CAT1>, <CAT1,CAT2>, <CAT2,CAT1>, and <CAT2,CAT2>, with pairs ordered from bottom to top. Seven, including the empty cache.

Each cache field now holds a complete payload. The state tells materialization how much space to reserve for it in the backing frame.
For <CAT1,CAT1>, we write two integers or floats and advance top by two slots. For <CAT2,CAT2>, we write two longs or doubles and advance top by four. The fields still extend the backing array, but the number of slots they represent depends on the state.

Two registers. Now room for two longs.

We can go further and distinguish the actual primitive types: <INT>, <FLOAT>, <LONG>, <DOUBLE>, and ordered pairs such as <INT,LONG> or <DOUBLE,FLOAT>. That lets the stack implementation choose a register representation as well as a slot width. We keep integer payloads in long fields and add double fields for floating-point payloads, which can travel in XMM registers on x64. A float retains its raw bits rather than being numerically widened to a double. Consecutive floating-point handlers can then operate on those payloads without shuttling them between general-purpose and floating-point registers.

The state determines which fields contain valid payloads and must be written back during materialization; unused representations must not be treated as stack values. The expansion configuration exposes that validity to the compiler, so those unused fields need not occupy registers either.

There is a bill for all this information. Four single-value states and sixteen ordered pairs, plus the empty state, give us twenty-one states. Each incoming state creates another handler variant to compile, and each viable variant contributes generated code.

Some handler/state combinations are impossible, and we can say so. The typed popInt rejects a cached operand whose kind is not INT using an unreachable-path directive. For iadd entering in <DOUBLE,INT>, the first pop succeeds, but the second encounters the cached double. Once specialization exposes that contradiction, the compiler propagates the unreachable marker back to the entry, discarding the preceding work and reducing the variant to a tiny trap. This reduces both the remaining compilation effort and the emitted code size.

To reduce the number of variants further, we can also choose not to cache some perfectly legal combinations.

For example, we could keep only the empty state, the four single-type states, and the four same-type pairs: nine states. A push that would create a mixed-type pair would instead write the existing cache and the incoming value to the frame, then return to the empty-cache state. <INT,DOUBLE> is legal for DASTORE, but we can still omit it and flush instead.

Whether we add states or drop them, the changes stay in the stack subclass and its expansion configuration.

The handlers still push, pop, and compute.

The Fast and the Curious

With those pieces in place, let us step back and see how far we have come.

We threaded the handlers, then used the verifier’s knowledge to remove checks and widen their indices. We taught the compiler to make different tradeoffs for these tiny handlers. Finally, we cached the top of the stack, keeping more interpreter state in registers.

To see how these changes translate into performance, we selected Sieve and Mandelbrot from the Are We Fast Yet suite. Both are arithmetic-heavy workloads that exercise the handler and operand-stack operations discussed above. All measurements are interpreter-only, with JIT compilation disabled.

Our starting point is Crema before threaded tail calls. For TOS, we compare the basic slot cache, the category cache, and the typed cache.

Threading gives both workloads a substantial boost, but neither catches HotSpot until we teach the compiler the handler-specific tradeoffs.

With the basic cache, Sieve runs about 48% faster than HotSpot; Mandelbrot, about 34%. Sieve heavily exercises baload and bastore.
Two differences likely help here. We quicken these bytecodes for the array type; in particular, bastore no longer needs HotSpot’s byte-versus-boolean check. Our two-entry primitive cache can also keep both the index and value in registers, whereas HotSpot caches only the top operand.

The category cache brings Mandelbrot to 41% faster. Mandelbrot is heavy on double arithmetic: the basic slot cache holds only one double, while the category cache can keep both operands in registers.

The typed cache is the interesting twist. Although llvm-mca estimates 7.5% fewer cycles than the category-cache version for the interpreter instruction sequence corresponding to Mandelbrot’s hot loop, the typed cache runs slower in the benchmark. One possible culprit is code size: more handler variants mean a larger instruction footprint, potentially increasing pressure on the instruction cache.

Two arithmetic-heavy workloads do not settle the performance of an entire interpreter. They do show that readable Java and competitive interpreter code can coexist — even when getting there takes quite a bit of teaching.

The End Credits

We started by asking how close ordinary Java could get to the assembly we wanted. The answer depended on how we divided the work between the interpreter’s source code and the compiler. The source describes the execution model and supplies knowledge the compiler cannot discover on its own. The compiler turns that description into machine code, sometimes with policies tailored to the interpreter.

The harder question is where the design should live. When the design lives only in comments or in the programmer’s head, the implementation can drift away from it. Expressed through the right abstraction, it becomes something we can maintain and extend — and something the compiler can turn into efficient code.

Escape analysis deserves a credit of its own. Together with scalar replacement, it lets an object remain a useful source abstraction without requiring an object in the generated code. Its fields become independent compiler values that can live in registers. Argument expansion carries that idea across handler boundaries. The design stays in the source. Its objects need not survive into the assembly.

We still care about every load, move, and spill. We would just rather not write each one ourselves.

There is still call overhead to address.
That is where we go next.

Chasing the Perfect Assembly was originally published in graalvm on Medium, where people are continuing the conversation by highlighting and responding to this story.

You can already download this release and check the release notes for more details.

GraalVM 25.3 brings several performance and security improvements, as well as updated language runtimes — keep reading to see what’s new!

Run even faster 🚀

GraalVM now includes a new priority inliner, available in both JIT and Native Image modes. It performs broader call-graph analysis to focus inlining on the most promising call sites, potentially improving the performance of generated-code and enabling further compiler optimizations. This means that many applications will see performance improvements by simply upgrading to the latest version.

Native Image now provides faster execution paths and optimized spinning for synchronized operations, improving locking performance. Its runtime bytecode interpreter has also been redesigned to enable tail-call threading between outlined bytecode handlers, significantly improving interpreter performance.

The Graal compiler additionally optimizes unsigned integer division and remainder operations by constant values using magic-number transformations.

Additional security hardening 🛡️

This release introduces new control-flow integrity options through -H:CFI. Control-flow integrity (CFI) is a security mechanism that helps prevent attackers from redirecting program execution to unexpected code locations. On AMD64, software-based checks can ensure that indirect branches land on valid targets. On AArch64, pointer authentication codes can protect return addresses stored on the stack. In addition, executable anonymous memory-mapping locations are now randomized by default.

Updated language runtimes

GraalJS now includes Node.js 24.18.1. It also implements the Iterator Includes, Iterator Join, and Iterator Chunking proposals, available in the ECMAScript staging mode (--js.ecmascript-version=staging).

GraalPy incorporates the Python 3.13.14 standard library and implements additional Python 3.13 features.

Expanded WebAssembly support

GraalWasm now recognizes WebAssembly branch hints, allowing if and br_if likelihood information to guide optimized code generation. This release also adds the table64 portion of the Memory64 proposal and experimental support for Wide Arithmetic operations.

Community

• Say hello to the Kotlin compiler on Native Image! The native image provides a drop-in replacement for the standard kotlinc command-line tool, while offering faster startup time and higher performance.
• Explore how manual reification helps the Graal compiler turn flexible data pipelines into highly optimized code.
• Join us at Devoxx Belgium for several GraalVM sessions across Native Image, Python, and AI!

Conclusion

We’d like to take this opportunity to thank our amazing contributors and community for all the feedback, suggestions, and contributions that went into this release.

If you have feedback for this release or suggestions for features that you would like to see in future releases, please share them with us on Slack, GitHub, or LinkedIn.

Now go ahead and try the new GraalVM! 🚀

— the GraalVM team

GraalVM 25.3 is here! 🎉 was originally published in graalvm on Medium, where people are continuing the conversation by highlighting and responding to this story.

Last year, Thomas, bearer of the One Graal, came to us with a prompt:

「 /goal make the GraalPy interpreter faster than CPython 」

To understand what Thomas was asking, it helps to know what the two interpreters are made of. The GraalPy interpreter is written in Java. CPython’s is written in C. So the real assignment was to make a Java interpreter outrun a C one, without giving up the high-level Java programming model.

The good news was that we controlled the compiler.

The bad news was that we controlled the compiler.

There are very few hard limits when you own the entire stack. There are also very few excuses.

If the branch predictor was unhappy, that was our problem.

If the register allocator was unhappy, that was our problem.

So we started looking for something dangerous to optimize.

The Giant Switch

The most obvious suspect was the interpreter dispatch loop. To keep the discussion concrete, let us start with a tiny program:

static int plus1(int x) {
    return x + 1;
}

On a stack-based virtual machine, this could be compiled into a bytecode sequence like:

iload_0
iconst_1
iadd
ireturn

Even if you have never looked at Java bytecode before, the instructions are fairly self-explanatory: load the first local variable (which happens to be the method parameter in this example), push the constant 1, add the two values, and return the result.

One natural way to implement such a bytecode interpreter is a large dispatch loop:

while (true) {
    int opcode = bytecodes[pc];
    switch (opcode) {
        case ILOAD_0:
            stack[sp++] = locals[0];
            pc++;
            break;
        case ICONST_1:
            stack[sp++] = 1;
            pc++;
            break;
       case IADD:
            int b = stack[--sp];
            int a = stack[--sp];
            stack[sp++] = a + b;
            pc++;
            break;
       case IRETURN:
            return stack[--sp];
       // imagine a few hundred more friends here
    }
}

Before continuing, it is worth acknowledging that this is not the only way to implement a bytecode interpreter. HotSpot’s template interpreter, for example, is famously efficient. Rather than relying on a giant switch loop, it generates platform-specific native code for executing bytecodes.

That option is powerful, but it also moves the burden onto handwritten or explicitly generated low-level machinery. Our challenge was different: keep the interpreter expressed through Java objects and methods, while still giving the compiler enough information to recover some of the same efficiencies automatically.

The real dispatch loop was, of course, much larger than this toy example, with hundreds of bytecode handlers.

Still, the execution pattern remains the same: every bytecode handler eventually returns to the same dispatch loop, which fetches the next opcode and jumps to the corresponding handler.

This architecture has many virtues. It is well understood, easy to maintain, and surprisingly effective. It also has a tendency to accumulate state. The program counter lives there. The operand stack lives there. The local variables live there. Profiling information lives there. Before long, every piece of interpreter state is flowing through the same compilation unit.

That last detail would eventually matter a great deal.

For now, all we saw was a giant switch sitting in the middle of one of our hottest execution paths.

Naturally, we blamed it for the performance gap.

Take I: Thread the Switch

The first theory was branch prediction.

At the end of each non-terminating bytecode handler, control returns to the switch. The interpreter reads the next opcode and uses the same dispatch branch to select the next handler. So every transition in our plus1 example passes through the same machine-code branch.

Modern processors do not wait politely for every branch to resolve. They speculate. The processor predicts where a branch will go and starts executing along that path before the branch has actually completed.

When the prediction is correct, much of that work is effectively free. When the prediction is wrong, the speculative work is discarded and execution restarts from the correct target. Ideally, the processor would learn that after iload_0 comes iconst_1, after iconst_1 comes iadd, and after iadd comes ireturn.

Unfortunately, the predictor does not see bytecodes. It sees machine instructions.

From the processor’s perspective, all of these transitions originate from the same dispatch branch.

To build some intuition, imagine that each branch instruction is a signpost. Whenever the branch resolves, the signpost turns to point toward the destination it just took. The next time execution reaches that signpost, the processor speculates by following its current direction. Under this simple model, the shared dispatch signpost will mispredict every transition in our example.

Real branch predictors use considerably richer history, but each time the branch executes, the predictor must still choose one specific target and begin speculating along that path.

This is the classic motivation behind threaded dispatch. The trick is to duplicate the signposts.

The bytecode sequence stays the same, but each handler gets its own copy of the dispatch branch at a different machine-code location.

The obvious question is how to generate such a layout. Fortunately, the replay itself is surprisingly straightforward.

We expose this through a feature of the Truffle Bytecode DSL. The dispatch sequence is marked for special treatment:

while (true) {
    int opcode = bytecodes[pc];
    switch (markThreadedSwitch(opcode)) {
        // ...
    }
}

Because we control the compiler, that marker can trigger a late code-generation step. During code generation, we record the machine code for the dispatch path, from the loop header through the table jump generated for the switch. At the very end of compilation, the compiler replaces each interpreter backedge with a copy of those exact machine-code bytes.

No re-optimization is required. No new register allocation is required.

As a result, all registers, memory operands, and addressing modes remain exactly as they were in the original dispatch sequence. The important difference is that the branch instruction is no longer shared by every bytecode transition.

Some patching is still required. Branches leaving the copied region, metadata references, and other bookkeeping details need to be adjusted. These details matter, but they do not change the basic idea: copy the generated dispatch path to each backedge.

One unpredictable dispatch branch becomes many more predictable ones.

That was the theory, at least.

The Rabbit Hole

As expected, threaded dispatch helped, but the magnitude never felt right.

Honestly, I never really bought branch prediction as the whole story.

So we opened the intermediate representation our compiler emits.

As compiler engineers, this is usually the point where we hope to find a small, local mistake instead of a new research project.

Fortunately, there was one.

The shared dispatch loop header was carrying around a surprising amount of register pressure.

To understand why this matters, imagine an interpreter that keeps enough state live to exceed the number of available registers. On x86–64, that is not as difficult as it sounds. Despite decades of progress elsewhere in computing, most of us are still developing on machines with 16 general-purpose registers. Intel APX promises relief, but it has yet to appear on the machines that generate our management update charts.

Eventually, some values must be spilled to memory. In our case, the scheduling heuristics had a tendency to pull interpreter states into the shared dispatch loop header.

The unfortunate part is that many of those states were not needed by every bytecode handler. An interpreter state that was only relevant to a handful of bytecodes could still compete for registers in the shared dispatch path executed by all of them. The more registers a handler needed locally, the fewer good choices remained for values live around the shared loop header.

A straightforward mitigation was to tweak the heuristics so fewer interpreter states were scheduled into the loop header.

This did not make register pressure disappear. It changed where the cost was paid. An interpreter state needed by one handler should ideally compete for registers in that handler, not in the shared dispatch path executed by every bytecode. That is a much better trade-off.

Ordinarily, increasing code size would be a concern.

At this point we were already duplicating the dispatch loop onto every interpreter backedge. Worrying about a few more instructions felt somewhat academic.

The optimization worked, surprisingly well.

Unfortunately, this was also where we fell into the rabbit hole.

We had reduced the cost of the shared dispatch path, but the compiler was still fundamentally reasoning about the same enormous program.

A giant switch had become a giant compilation unit. A giant compilation unit had become a giant live-range problem.

Values from unrelated bytecode handlers were still competing for the same limited register budget. For an interpreter, not all values are equal. Spilling a rarely used handler-local temporary is annoying. Spilling the program counter, the stack pointer, the bytecode array, or frequently accessed frame state can add memory traffic to almost every bytecode transition.

While a register allocator can often find excellent solutions, it cannot exhaustively explore the optimization space of a large compilation unit in a reasonable amount of time.

It must therefore make more heuristic decisions, and heuristic decisions inevitably leave some performance on the table.

Register allocation was only where the problem first became obvious. The same shape affected every optimization that had to reason about the interpreter as one enormous body.

We could keep tuning heuristics and teaching the compiler new tricks.

Or we could ask a more uncomfortable question.

Why was the entire interpreter being optimized as one giant compilation unit in the first place?

Take II: Escape the Giant Switch

Once we framed the problem as a giant compilation unit, the obvious solution seemed equally obvious.

Split it.

After all, compilers already know how to compile multiple methods independently. Why force the entire interpreter through one enormous optimization problem?

In fact, there is a remarkably straightforward way to do exactly that. Every bytecode handler can simply become its own method:

@DontInline
static void iload0(...) { ... }

@DontInline
static void iconst1(...) { ... }

@DontInline
static void iadd(...) { ... }

Now every handler is compiled independently. The giant compilation unit disappears. The giant live-range problem disappears. The register allocator can focus on one bytecode handler at a time.

The problem is gone. Unfortunately, so is most of the performance.

The issue is that compilation boundaries are not free.

For an interpreter, there is quite a lot of state to carry around. The bytecode stream. The program counter. The operand stack. The stack pointer. Profiling information. Exception state. Various pieces of bookkeeping accumulated over years of evolution.

Inside a single compilation unit, many of these values can remain virtual. The compiler is free to keep them in registers and move them around as it sees fit.

Across a method boundary, that illusion breaks down: values must cross a calling convention, and virtual state may need to be materialized.

In a language like Java, primitive interpreter state is particularly awkward. One option is to store everything in an object and pass that object from handler to handler. The register allocator will certainly appreciate the smaller compilation units.

The memory subsystem, less so.

We would have traded a register allocation problem for a memory traffic problem. What we really wanted was something contradictory.

We wanted each bytecode handler to be compiled independently, as if it were its own compilation unit.

At the same time, we wanted interpreter state to flow between handlers as if no compilation boundary existed at all.

In other words, we wanted optimization across compilation units.

Normally, those words do not belong in the same sentence.

The Valhalla-Shaped Trick

The obvious question was how to move interpreter state across compilation boundaries without sacrificing the optimization opportunities we had just fought so hard to recover.

The idea itself was not entirely new.

Project Valhalla had already spent years exploring a similar observation: programmers like objects, but compilers often prefer their contents.

Consider our running example:

class State {
    int pc;
    int sp;
}

static void iadd(State state, int[] stack) {
    int b = stack[state.sp--];
    int a = stack[state.sp--];
    stack[++state.sp] = a + b;
    state.pc++;
}

From the interpreter author’s perspective, this is exactly what it should be: a small mutable object carrying interpreter state from one bytecode handler to the next. From the compiler’s perspective, however, the interesting part is rarely the object itself. The interesting part is the values it contains.

Conceptually, instead of reasoning about State state, the compiler would much rather reason about <pc, sp>.

So we took the idea and developed it further for interpreter state. Rather than passing interpreter objects across compilation boundaries, we expand selected fields into a tuple of values. Together with the existing handler arguments, that gives the compiler the boundary tuple it actually wants to optimize. To preserve the original programming model, the compiler leaves the original handler signature unchanged and synthesizes a small stub:

static void __stub_iadd(int pc, int sp, int[] stack) {
    State state = new State(pc, sp);  // To be virtualized
    iadd(state, stack);               // To be inlined
}

After inlining, escape analysis can often remove the reconstructed state object from the optimized representation and replace its fields with compiler values. Even when it cannot do so globally, Graal’s control-flow-aware Partial Escape Analysis can apply the same optimization on the fast path where object materialization is unnecessary.

Expanding interpreter state into a tuple solves only half of the problem. The tuple still needs to come back, but Java methods are much happier accepting many inputs than returning many outputs. So the generated stub grows a tuple return value:

// Pseudo-Java
static <int, int, int[]> __stub_iadd(int pc, int sp, int[] stack) {
    State state = new State(pc, sp);  // To be virtualized
    iadd(state, stack);               // To be inlined
    return <state.pc, state.sp, stack>
}

At first glance, this may look like constructing and returning a tuple object. The important detail is where the updated values land. The generated calling convention returns the tuple through the same locations that carried it in. If pc enters the stub in one register, the updated pc' comes back in that same register. The caller-side write-back can then be inserted mechanically:

// Pseudo-Java
<pc', sp', stack> =
    __stub_iadd(state.pc, state.sp, stack);
state.pc = pc';
state.sp = sp';

Interpreter state now follows a round trip:

The state objects preserve the Java programming model on both sides of the boundary. Interpreter authors keep working with objects, fields, and ordinary method signatures, while the compiler uses the tuple to carry selected state between compilations as register values.

Escape analysis also runs independently in the caller, which may keep the original state object virtual.

The write-back itself does not necessarily become memory traffic. If both state objects remain virtual, the updated values may continue flowing as compiler values throughout the entire round trip. In practice, this gives us much of what we wanted from escape analysis across compilation boundaries, without requiring the two compilations to become one.

The register allocator offers another perspective. Previously, the dispatch loop and all bytecode handlers formed one enormous register-allocation problem. Now the caller and each handler are allocated independently, with fixed argument locations connecting them into one continuous execution.

The Hidden Boundary Tax

There are still some limits to what this interface can express. In principle, we could carry every interpreter state across the call boundary. In practice, we must reserve part of the register budget for each handler’s local work. Even a simple bytecode such as iadd needs scratch registers for its local calculation, so the boundary tuple cannot occupy every useful register.

In the old giant compilation unit, an unselected value could still be visible to the inlined handler body and remain register-resident through scalar replacement. After outlining, a value that is not part of the boundary tuple is no longer carried into the handler as a compiler value. If the handler needs it, it must recover the value from materialized interpreter state through an ordinary memory access.

Usually this is still acceptable. We can select the most important states, and leave statistically negligible state to be recovered from memory when a handler actually needs it.

The more unavoidable issue is the call itself.

Besides ordinary call mechanics such as return-address bookkeeping and frame setup, a managed runtime like Native Image has to emit safepoint metadata for the call, describing where live references are. Unlike non-call operations, calls force the compiler to treat the callee as a black box. Live references residing in registers may be clobbered during the call, even if our special calling convention restores them once the call returns. That means the references need a GC-visible home, which often means a stack slot.

The outlined call boundary therefore turns part of the original register-pressure problem into a backup-and-restore problem around the stub call.

Yet the call also gives us the clue for escaping that cost. When the handler returns, the updated tuple already occupies the locations where the next handler expects its inputs. At that point, the obvious question is no longer just how to make the call cheaper. Why are we returning to the caller at all?

Thread the Calls

The answer, of course, is that we do not.

Instead, each handler stub performs the dispatch itself. This optimization is often called tail call threading. After executing the bytecode implementation, it fetches the next opcode, looks up the corresponding handler stub, and jumps directly to it. The bytecode stream therefore becomes a first-class part of the handler interface, extending the tuple to <pc, sp, stack, bytecodes>.

The generated code now looks roughly like this:

// Pseudo-Java
static <int, int, int[], short[]>
__stub_iadd(int pc, int sp, int[] stack, short[] bytecodes) {
    State state = new State(pc, sp);  // To be virtualized
    iadd(state, stack);               // To be inlined
    int nextOpcode = bytecodes[state.pc];
    jump handlerTable[nextOpcode]
        with <state.pc, state.sp, stack, bytecodes>
}

The specialized calling convention makes this natural: the jump requires no reshuffling and transfers the current interpreter state directly.

Viewed from a distance, the handlers resemble LEGO bricks: the shared tuple interface forms the studs that let them snap directly together.

The dispatch loop still exists. It simply stops getting invited to every bytecode.

The Benchmark Everybody Came For

At this point, we should probably return to the benchmark that drove this whole adventure.

To recap, the first suspect was branch prediction in the dispatch loop, and we threaded the switch to attack it. The spill came later; we tuned the scheduling heuristic and pushed the spill cost into individual handlers. Eventually, the compilation unit itself became suspicious. We outlined the handlers, then threaded the tail-call between them.

The final, threaded-tail-call configuration is GraalVM 25.1 as released. The other configurations use that same release with the relevant optimizations selectively disabled, allowing us to reconstruct each stage of the journey. All measurements are interpreter-only, with GraalPy’s JIT compilation disabled.

We selected a few arithmetic-heavy benchmarks that are representative of the interpreter optimizations discussed above. Other workloads are dominated by different costs, such as guest-language calls or attribute access, and therefore depend more heavily on the implementation of the Python runtime itself.

bytecode-benchmark fits the story most clearly. The baseline starts below CPython. Threading the switch brings it to roughly parity, and tuning the scheduling pushes it ahead.

Then we got greedy. To thread execution directly from one handler to the next, we first outlined the handlers into separate compilation units, and hit the boundary tax. The handlers were smaller, but every call was surrounded by bookkeeping memory accesses.

Tail-call threading is what makes that structure pay. Once the updated tuple can flow directly from one handler to the next through the specialized calling convention, bytecode-benchmark moves comfortably ahead of CPython.

arith-binop and sieve start from stronger baselines but follow the same broad progression.

Overall, the benchmark result is not simply that threading wins. It is more specific: threading makes the handler boundary cheap enough that outlining stops being structurally fatal.

That leaves a more interesting question. If the compilation boundary between caller and handler no longer has to be an optimization boundary, what about the boundary between one handler and the next?

“One More Thing”

The most frequently accessed values in a stack interpreter are, unsurprisingly, the values at the top of the stack. A typical arithmetic bytecode may load values from the operand stack, perform an operation, and immediately push the result back. Even after escaping the giant switch, these stack accesses remained firmly on the hot path.

This is not a new observation. Top-of-stack caching is a well-established interpreter optimization. The question was how to make it expressible in ordinary Java code while still giving the compiler a register-level representation to optimize. The answer, again, was the tuple.

By this point, interpreter state was already flowing between handlers as a tuple of register-resident values. Nothing limited that tuple to the existing interpreter state, such as the program counter or stack pointer: it could also carry recent operand-stack values, keeping them in registers across handler boundaries.

Conceptually, the handler tuple grows from <pc, sp, stack, bytecodes> to <pc, sp, stack, bytecodes, tos1, tos2, tosDepth>.

Here tosDepth says how many cached values are currently valid. When tosDepth is 1, tos1 is the current top of stack. When tosDepth is 2, tos2 is the current top of stack, while tos1 is the value beneath it.

At this point, some readers may be counting registers and becoming increasingly uncomfortable. Under a conventional calling convention, they would be right. Sooner or later additional arguments would spill onto the stack, undoing much of the benefit we were trying to achieve.

Fortunately, we control the compiler.

Nothing requires us to stop at the six integer argument registers provided by the platform ABI. Handler stubs never cross a language boundary, so we are free to employ a considerably more adventurous calling convention and use essentially the entire allocatable register file for interpreter state. The tuple may be growing, but it is still very much intended to stay in registers.

In our running example, iload_0 pushes the local value into tos1. Then iconst_1 pushes the constant into tos2. Finally, iadd consumes tos2 and tos1, then leaves the result in tos1.

The important part is not merely that tos1 and tos2 avoid memory accesses inside one handler. The value loaded by iload_0 remains in a register across iconst_1 and into iadd, without ever touching the operand stack.

No stack loads.

No stack stores.

At least not immediately.

Of course, reality is slightly less convenient. Two registers can only hold two stack values. Sooner or later a bytecode sequence will push a third value, then a fourth, and eventually the cache must spill into the backing operand stack. Likewise, some handlers may need to materialize cached values before interacting with code that expects the operand stack to reside in memory. The interpreter therefore carries tosDepth as part of its state and lets individual handlers decide when values should remain in registers and when they must be synchronized with the backing stack array.

Without further help, every push and pop now has to account for all possible cache states. A push is no longer simply stack[++sp] = value;. It starts to look more like:

switch (tosDepth) {
    case 0:
        tos1 = value;
        tosDepth = 1;
        break;
    case 1:
        tos2 = value;
        tosDepth = 2;
        break;
    case 2:
        stack[++sp] = tos1;
        tos1 = tos2;
        tos2 = value;
        break;
}

A pop has the same problem in reverse.

After spending several sections moving interpreter state into registers, we had accidentally introduced a new runtime state machine.

The (Compile-) Time (State) Machine

If tosDepth merely describes the shape of the cached stack, perhaps it should not travel in the tuple at all. Instead, we could turn the runtime state machine into a compile-time one, sending that decision backward in time from every bytecode execution to handler generation.

Consider iadd written in the most boring possible way:

static void iadd(...) {
    int b = stack.pop();
    int a = stack.pop();
    stack.push(a + b);
    state.pc++;
}

Without specialization, each pop and push must inspect tosDepth at runtime, as in the push example above.

Instead of generating a single handler that must reason about every possible cache state, we generate multiple handler variants. Each variant gets assigned a constant tosDepth, which is enough for ordinary compiler optimizations to fold away the irrelevant arms of push and pop. After those branches disappear, the updated tosDepth often becomes deterministic as well. Dispatch can then use that value to choose the next variant.

Returning to our LEGO example, imagine that each bytecode brick now bundles several handler variants, one for each possible incoming tosDepth. We stack these composite bricks vertically, and the tosDepth produced by one handler selects the path into the next.

The state machine still exists, but it no longer lives as control flow inside every handler. It lives in the transitions between handler variants.

Now consider the iadd<2> specialization. The compiler knows that both operands already reside in registers. The first pop becomes int b = tos2;. The second pop becomes int a = tos1;. And the push becomes tos1 = a + b;.

After constant folding and dead-code elimination, the handler is essentially reduced to tos1 = tos1 + tos2;.

Consequently, tosDepth no longer needs to occupy a runtime slot in the tuple.

The columns are not runtime branches; they are separately generated handler variants. The highlighted path follows iload_0<0> to iconst_1<1>, then iadd<2> and ireturn<1>. Each handler’s output cache shape determines the next variant, so neither a runtime tosDepth value nor a test of it appears along the path.

We traded runtime state transit for instruction bytes: multiple handler variants eliminate a runtime value and its control flow, freeing a register for actual interpreter state. The previous sections taught the interpreter how to carry state efficiently across compilation boundaries. This section taught it that some state never needed to travel in the first place.

The remaining concern is register pressure. For the mechanism to work well, the handler interface needs enough registers to carry two or more cached top-of-stack values in addition to the existing interpreter state. That is already a tight budget. GraalPy’s tail-call-threaded handlers pass a fairly heavy argument tuple today, and adding more top-of-stack values can exhaust registers and push other state back to memory.

The situation is even trickier because the Python stack can hold both primitive values and object references. Those may need special treatment, or even separate cached top-of-stack values, which would make the interface wider again. At that point, the optimization starts fighting the same register-pressure problem it was meant to avoid.

We are still exploring ways to mitigate this register cost, or at least warn interpreter authors when the handler interface becomes too wide.

Take III: ?

This article started with a giant switch.

The giant switch led to a spill.

The spill led to a giant compilation unit.

And the giant compilation unit turned out to be hiding far more than a few misplaced registers.

We first threaded the switch, giving each bytecode handler its own dispatch branch. We then tuned scheduling so handler-local state spilled only where necessary, rather than across the entire dispatch loop. Finally, we outlined the handlers into separate compilation units and connected them through a specialized tail-call convention. Interpreter state crosses those compilation boundaries as a tuple of values in fixed register locations, allowing the handlers to remain separate compilation units without turning their boundaries into optimization boundaries.

The threaded-handler implementation shipped in GraalVM 25.1.3 and is enabled by default in GraalPy. On the interpreter-only, arithmetic-heavy workloads shown above, it takes bytecode-benchmark from below CPython to comfortably above it, while arith-binop reaches roughly three times CPython.

This does not make every Python workload three times faster. Calls, attribute access, and other runtime operations are dominated by different parts of the GraalPy implementation. Even within the handler interface, registers remain a finite resource: carrying more interpreter state eventually risks pushing existing values back to memory.

That is also where the next experiment begins. If compilation boundaries no longer prevent values from remaining visible to the optimizer, the same interface can carry cached operand-stack values directly from one handler to the next. The mechanism works; finding the right register budget is still ongoing work.

For now, the giant switch is gone.

Until the next rabbit hole.

Escaping the Giant Switch was originally published in graalvm on Medium, where people are continuing the conversation by highlighting and responding to this story.

AI is transforming how software is built, but many of its benefits are still focused on people who can already code. Coding agents make developers more productive because they can write, run, and revise software. Ordinary application users should be able to benefit from a similar kind of transformation without becoming programmers themselves.

An application user often knows the outcome they need: a particular search, report, validation rule, visualization, routing policy, or workflow. They can very well describe that outcome without knowing how to implement it. However, they cannot be expected to study extension points or review code generated on their behalf.

But would you let ordinary users install AI-generated code into a production application without anyone reviewing it? At first glance, the only responsible answer is no, no, and again no! But that assumes generated code must be trusted before it can run.

What if generated code could be useful without being able to perform destructive actions directly?

That is the motivation behind our Graal Script Agent library.

From prompt to result

Graal Script Agent is a library that lets applications turn end-user prompts into sandboxed plugins. The application owner defines the allowed extension points. The model generates each script from the user’s prompt and extension contract without having access to production data. The application can then run it locally whenever needed.

As a first demo, we have added a new magic Script Agent tab to everyone’s favorite example, PetClinic:

Now put yourself in the position of one of your users. Frank is a veterinarian trying to follow up with a pet owner. He has forgotten the owner’s name, but remembers that the owner lives somewhere in Madison. Let’s assume PetClinic’s built-in search supports owner lookups by last name only, so he is stuck.

Frank is amazing with animals but completely clueless about software. Today is his lucky day because it can stay that way. Instead of learning a complex query screen or a query language, he simply describes what he remembers and the data he wants:

“Show owners in Madison with their telephone numbers.”

And this is the result:

He gets what he wanted: a list of owners in Madison, with each owner’s telephone number shown alongside their name, perhaps enough to refresh his memory.

What happened here? The agent selected the query extension point and generated a script against the query-only APIs exposed by the application. Because every capability in this extension point is non-destructive, PetClinic can execute the script directly and display its result.

Before we move on, notice the Add to Find Owners page button below the result. Clicking it persists the generated script as a plugin and makes this query available directly from PetClinic’s regular Find Owners page.

Whenever someone runs the saved query, the plugin executes locally against current data without another model call. Production objects stay inside the application, and the functionality remains available until it is removed, without anyone reviewing generated code.

A query is the straightforward case because it cannot change application data. But what if Frank asks PetClinic to make a change?

“Add a dog named Fido born 2022–05–01 for George Franklin and add a visit on 2026–03–01 for an annual checkup.”

This time, the agent selects a different extension point: one designed for data modifications. The generated script can query owner data and call an API for creating and modifying pets and owners. During script execution, however, the host records the requested modifications instead of committing them and displays the result.

Frank can now review the proposed pet and visit and choose whether to execute the modification. He reviews the domain-specific result, not the generated code. If he presses Execute, PetClinic validates and persists the approved modifications.

The selected extension point sets the security posture: queries can run directly, while modifications require review and approval.

That is the core idea. Now let’s find out how you can build such plugin mechanisms yourself with Graal Script Agent.

Defining the Extension Points

An extension point is a place where an application deliberately allows new behavior to plug in. In Java, it can be expressed as an interface that defines what a plugin must return and which application APIs it may use.

PetClinic’s extension contract can be simplified to this:

sealed interface Extension
        permits QueryExtension, ModificationExtension {
}

non-sealed interface QueryExtension extends Extension {
    QueryResult execute(OwnerQueryApi ownersApi);
}

non-sealed interface ModificationExtension extends Extension {
    void execute(OwnerQueryApi ownersApi,
            ModificationApi modificationApi);
}

interface OwnerQueryApi {
    List<OwnerView> findByCityStartingWith(String cityPrefix);
}

interface ModificationApi {
    void addPet(String ownerFirstName, String ownerLastName,
            String petName, String petTypeName, String birthDate);

    void addVisit(String ownerFirstName, String ownerLastName,
            String petName, String visitDate, String description);
}

Extension is the starting point for schema discovery. Its sealed hierarchy defines the available extension shapes, while each execute method defines
the script’s entry point and the application APIs available to it. The child interfaces remain non-sealed so the completed script can be bound to the
selected interface. This single-method shape is probably the most common, although extension contracts may contain multiple methods and richer type hierarchies.

With the extension point defined, generating an extension script only requires a model connector, a guest language, and the user’s prompt:

Model model = /* LangChainModel.of(...) or SpringAiModel.of(...)*/;
String prompt = "Show owners in Madison with their telephone numbers.";

Script<Extension> extensionScript;
try (ScriptAgent agent = ScriptAgent.newBuilder(model)
                           .language("js").build()) {
    extensionScript = agent.generate(
            Extension.class,
            prompt);
}

First, Graal Script Agent discovers the contract starting from Extension, presents it to the model, and asks the model to produce one of its permitted extension types. For Frank’s first prompt, that is a QueryExtension. For his second, it is a ModificationExtension. If the request cannot be implemented against the schema, generation fails with a useful message instead of returning an invalid plugin.

In this example, language(“js”) configures JavaScript as the scripting language. JavaScript is compact and runs locally through embedded GraalJS. Graal Script Agent can also use GraalPy to author Python scripts if preferred.

Against the simplified contract above, the JavaScript generated for Frank’s modification request could look like this:

util.implement(types.ModificationExtension, {
  execute(ownersApi, modificationApi) {
    modificationApi.addPet("George", "Franklin", "Fido", 
                           "dog",    "2022-05-01");
    modificationApi.addVisit("George", "Franklin", "Fido", 
                             "2026-03-01", "annual checkup");
  }
})

The script agent runtime exposes helpers such as util.implement to make it easier for the model to fulfill the contract. The framework handles these internal details. More difficult prompts or larger schemas naturally produce more elaborate scripts, but this shows the basic shape.

This example defines the plugin contract using Java interfaces and lets Graal Script Agent discover it automatically. The extension-point guide explains how to design such contracts in much more detail.

Sandboxing the Plugin

The generated Script<Extension> can be serialized and persisted, but it is not an active plugin. Before the application can use it, the script must be bound to a GraalVM polyglot context for execution:

try (Context context = Sandbox.UNTRUSTED.newContext(
        extensionScript.language())) {
    Extension extension = extensionScript.bind(context);

    if (extension instanceof QueryExtension query) {
        QueryResult result = query.execute(ownerQueryApi);
        display(result);
    } else if (extension instanceof ModificationExtension modification) {
        ModificationPlan plan = new ModificatinPlan();
        modification.execute(plan, ownerQueryApi);
        if (reviewByUser(plan)) {
            validateAndPersist(plan);
        }
    }
}

Sandbox.UNTRUSTED treats the generated source as potentially adversarial. It blocks host filesystem, network, process, environment, and arbitrary Java access; runs the guest in an isolated runtime; and limits CPU time, memory, threads, output, and program complexity.

Graal Script Agent secures the boundary between that guest runtime and the application through a schema-driven host binding. The plugin can access only the members and types declared by the extension schema. Undeclared members remain inaccessible even if the underlying Java object exposes more functionality.

Neither layer can make a dangerous exposed API safe. Exposed host methods must still enforce authorization, validation, tenant boundaries, and side-effect policy. For a deeper discussion of sandbox policies, resource limits, isolates, and production considerations, please see our recently published blog post on sandboxing.

Giving the Model Context

Coding agents became dramatically more useful when they got access to a shell. Early assistants mostly suggested code. Modern agents write code, run it, inspect the result, and revise. Code became the universal adapter between the agent and its environment.

Graal Script Agent applies the same idea inside a boundary controlled by the application. Frank’s prompt describes the result he wants, but not PetClinic’s Java API. The generated schema prompt supplies that grounding: it describes the available methods, types, records, enum values, and expected result shapes in language-specific form for JavaScript or Python.

For more complex extensions, Graal Script Agent adds an iterative feedback loop using application-controlled authoring tools rather than shell access:

• Draft editing lets the model build and revise one script.
• Schema inspection provides type details on demand when the API is too large to present in full.
• Sample inspection shows representative synthetic or sanitized application objects to the model and it can use a script to inspect it.
• Mock execution runs the draft in a bounded environment so the model can observe failures and revise it.
• Application-defined tests check the behavior before accepting a plugin and give feedback to the model when a test fails.

Not every extension needs every tool. A clear prompt and a small schema may be enough for the Madison query. Larger or more context-dependent extension points benefit from samples, execution feedback, and tests. When application-defined tests are configured, completion succeeds only after all of them pass.

By default, the model receives the user’s prompt and the schema describing the extension API, not live application data. Sample inspection is an explicit opt-in that makes selected application objects visible to the model. Applications handling sensitive data should use synthetic or sanitized samples, or a local model.

Turn on the music!

As a kid, I was fascinated by Winamp’s music visualizations. I remember staring at them for hours. Creating one myself felt out of reach: too much graphics programming and too much math.

I am much, much older now, but Graal Script Agent lets me create a plugin system where I can prompt my own Winamp visualizations using natural language by exposing an extension point as small as this:

void draw(PixelBuffer buffer, int tick, AudioFrame audio);

The generated plugin receives a pixel buffer and a small audio summary on every frame. That tiny contract is enough to generate bars, waves, pulses, beat flashes, and spectrum effects without exposing the UI toolkit, audio system, files, or threads.

Now let’s prompt it with “two rotating dodecahedra”:

The model is not part of the rendering loop; only the generated scripts are. These scripts run locally, filling a 320 × 180 pixel buffer while the demo targets 30 frames per second. GraalJS compiles the hot drawing function, so the visualization runs smoothly even inside the sandbox.

The source code is available here.

Filtering compiler graphs!

We also integrated Graal Script Agent into Ideal Graph Visualizer (IGV), a tool the GraalVM team uses to inspect compiler graphs. These graphs can be very large, so we often write custom filters by hand to find the few nodes or paths relevant to an investigation. With Graal Script Agent, we can instead describe what we want to find or highlight, and it generates the corresponding filter plugin.

IGV demonstrates the opposite end of the spectrum from the tiny Winamp contract. It exposes a substantial graph API, while the concrete node classes, properties, and relationships vary with the compiler graph being inspected. The static schema describes the stable graph operations, but the exact shape of the data becomes clear only at authoring time. Sample inspection lets the model examine representative graphs and ground its generated filters in observed node names, properties, dependencies, block structure, and execution frequencies instead of guessing from generic conventions.

Below is a screenshot of IGV, filtering the most common control flow path of the graph. This is a very useful extension for our workflow.

The source code for this integration will be available soon.

Where It Fits and Where It Doesn’t

Some behaviors should not be exposed as prompt-authored extensions at all. Core price calculations, authorization decisions, or irreversible bulk operations may require stronger assurance and a regular development process.

The best candidates are bounded customizations such as saved searches, ad-hoc reports, routing rules, UI filters, dashboard cards, visualizations, data exploration, and validation logic. They are often specific to one user, team, tenant, or task, valuable enough to matter, but too specialized to justify development.

Extensions can also propose modifications. The application then needs a stronger workflow: review the proposed operations, present them in domain terms, and require confirmation before enabling writes. To be honest, we haven’t fully explored this space, so we don’t exactly know where the limits are.

Not every useful extension needs to become a permanent plugin. Often the most value comes from complex one-off tasks: the user knows the outcome they need but not how to achieve it through the application’s existing screens and controls. The generated extension can run once and then be discarded.

Like a chatbot, the interaction begins with a natural-language request. Unlike a generic chatbot, the result is integrated with the application’s types, data, UI, and safety workflow. It can perform the task through application-defined APIs and present the result where the user already works.

Try it yourself

Graal Script Agent is in preview, but it is ready for you to try!

The docs include a getting-started guide with a minimal application covering schema discovery, script generation, sandboxed execution, and authoring tools.

Start small. Define one query-only Java interface. Expose only methods that you’re comfortable allowing untrusted code to call. Then prompt the agent to implement it and run the result inside an appropriately configured sandbox.

We have built only a handful of applications with this so far, which is why feedback matters a lot at this stage. If prompt-authored extensions sound useful for something you are building, get in touch and join the #script-agent channel in our community Slack. Feel free to open any issues you encounter on GitHub.

Further reading

• Graal Script Agent manual: Start here for setup, schema discovery, runtime binding, and authoring tools
• Blog Post on Sandboxing Script Extensions with GraalVM: Find out more about sandbox policies, resource limits, isolates, and production considerations.
• Micronaut PetClinic Script Agent demo: The demo shown at the beginning.
• Want to contribute? Check out the GitHub repository.

When Prompts Become Plugins was originally published in graalvm on Medium, where people are continuing the conversation by highlighting and responding to this story.

Today, we’re pleased to announce the release of GraalVM 25.2!

GraalVM 25.2 is the latest release on our innovation release train, accelerating the delivery of new features and improvements. Meanwhile, GraalVM 25.0 will continue receiving regular Critical Patch Updates (CPUs) for applications that require production stability.

You can already download GraalVM and check the release notes for more details.

GraalVM 25.2 brings sandboxed application plugins, reduced memory usage, G1 in Native Image across all platforms, and more — keep reading to see what’s new!

Sandboxed application plugins with Graal Script Agent 🤖

This releases introduces Graal Script Agent. Graal Script Agent turns natural-language requests into sandboxed application plugins that run locally, so users can customize applications for their specific needs without writing or reviewing code.

Many applications could benefit from this functionality, particularly those including dashboards, reporting, and data exploration. Extensions can also propose modifications, but the application should record and preview those operations for approval instead of allowing the generated script to commit them directly. The selected extension point determines the policy: a read-only query may execute immediately, while a modification requires validation and confirmation.

Application developers define extension points that specify what kinds of plugins may be generated and which application APIs they can access. Given a user request, a model uses these definitions to generate a JavaScript or Python plugin. The extension point also determines how the application handles the result: for example, a read-only query may run immediately, while a modification can require confirmation.

Generated plugins run in a restricted GraalVM polyglot context with resource limits. Schema-driven bindings restrict their access to the application APIs explicitly exposed to them.

A plugin can run once and be discarded or be stored for later use. A stored plugin runs locally against current application data without requiring another model call.

To learn more about Graal Script Agent and see several use cases in action, read the related blog post.

Reduced memory usage with compressed references 🚀

GraalVM 25.2 introduces compressed references in Native Image, enabled by default. On 64-bit systems, references between managed objects are now stored as 32-bit heap-relative values instead of full 64-bit addresses.

This more compact representation can reduce the memory occupied by reference-heavy object graphs and reference arrays. It can also improve cache efficiency because more references fit into the processor’s fast cache. Build-time objects stored in the executable’s image heap may also occupy less space, although the effect on the total executable size depends on the proportion of code, metadata, resources, and image-heap data it contains.

In our test, a Micronaut web application using Oracle Database showed a 39% reduction in RSS under load with GraalVM Community Edition 25.2 compared with 25.0:

Compressed references do not make the executable 32-bit: native addresses and other native data remain 64-bit. The feature limits the managed heap to 32 GB. Applications requiring a larger heap can disable it at build time with -H:-UseCompressedReferences.

G1 across all platforms!🎉

Native Image now supports G1 GC on Windows! It can provide better throughput and lower latency, particularly for multithreaded applications and larger heaps. To enable it, build your application with --gc=G1.

This release also brings image startup and size improvements. Native images using G1 now start faster because more initialization work is completed at image build time, with applications that have larger image heaps seeing the greatest benefit. Native executables using G1 are also smaller when built with profile-guided optimizations (PGO) or -Os.

Vector API Support by Default 🚀

In this release we have enabled Java Vector API support by default when the jdk.incubator.vector module is part of the boot module layer.

The Vector API allows supported processors to perform the same operation on multiple values simultaneously using SIMD instructions. This can accelerate computation-heavy workloads such as machine learning, numerical computing, image processing, and data analysis, with results depending on the workload and target hardware.

Community and Ecosystem 🌎

• Thomas Wuerthinger will speak at IntelliJ IDEA Conf 2026 about Sandboxing AI Agents with GraalVM — you can still register to join online.
• Check out the Antigravity session visualizer, built by Guillaume Laforge using Micronaut, LangChain4j, and GraalVM!

• Micronaut 5.1 was released just yesterday, with Oracle chat-memory auto-configuration and other features — see what’s new.
• The Reachability Annotations project, released by HEBI Robotics, generates Native Image metadata at compile time, simplifying configuration for reflection-heavy and FXML-based applications.
• Meet KubeMicroVM, a new Kubernetes operator and CLI for AWS Lambda MicroVMs, built with Quarkus and Native Image!
• Inspect Parquet files directly in your browser: Gunnar Morling used GraalVM Web Image to compile Hardwood’s dive to WebAssembly.

Conclusion

We’d like to take this opportunity to thank our amazing contributors and community for all the feedback, suggestions, and contributions that went into this release.

If you have feedback for this release or suggestions for features that you would like to see in future releases, please share them with us on Slack, GitHub, or LinkedIn.

Now go ahead and try the new GraalVM! 🚀

— the GraalVM team

GraalVM 25.2 is here! 🎉 was originally published in graalvm on Medium, where people are continuing the conversation by highlighting and responding to this story.

Applications increasingly execute scripts that are supplied by customers, loaded dynamically, or generated by AI. This post shows how GraalVM sandboxing can restrict what those scripts access, limit the resources they consume, and isolate failures from the host application.

This post is for you if:

• You are developing a script extension system.
• You run customer-provided scripts on your server.
• Your application or AI model generate scripts.
• You embed JavaScript or WebAssembly and do not trust the code or its input.

Using a JavaScript discount rule as a running example, we progress from trusted application code to fully untrusted source. The same approach works whether the host runs on the JVM or as a native executable built with Native Image.

Why script extensions need sandboxing

Modern SaaS applications often let organizations customize business logic instead of forcing every customer through one fixed workflow. No product can anticipate every business model, integration, or policy, so extensibility is a key driver of adoption. An entire industry has grown around customizing business applications.

A custom extension fills in behavior that the application deliberately leaves open. The application defines which data the extension receives, which operations it may call, and which result it must return. The extension supplies the missing decision, transformation, or workflow. Unlike configuration, which selects behavior the product already implements, a script extension can express logic the product developers did not anticipate.

Extensions often take the form of small scripts evaluated at runtime. Scripts are particularly convenient because they can be loaded and changed without rebuilding the application.

When an application starts executing extension code, it crosses a boundary from trusted, well-audited code to more or less unknown territory: The extension code may contain an accidental infinite loop, allocate too much memory, process malicious input, or deliberately attack the runtime.

All the features discussed here are available in both Oracle GraalVM and GraalVM Community Edition.

A discount rule extension

Throughout this post, we use a discount-rule extension that receives an Order and returns a discount rate. It only needs the order total, so Order exposes a single method:

public final class Order {

    private final double total;

    public Order(double total) {
        this.total = total;
    }

    @HostAccess.Export
    public double total() {
        return total;
    }
}

A rule maintained with the application might look like this:

Source rule = Source.create("js", """
                (order) => {
                    if (order.total() >= 100) {
                        return 0.10;
                    }
                    return 0.0;
                }
                """);

try (Context context = Context.newBuilder("js").build()) {
    Value discount = context.eval(rule);
    double rate = discount.execute(new Order(120)).asDouble();
    System.out.println(rate);
}

The flow has four parts. A Source represents the extension code independently of its execution. A Context contains the guest application state and configuration. context.eval(rule) evaluates the source in that context and returns a Value representing the JavaScript function. Calling execute() invokes that function with the exported Order.

The same Source can be evaluated in multiple contexts, with each evaluation producing a Value owned by that context.

Because no sandbox policy is specified, the context uses TRUSTED. Java and JavaScript execute in the same runtime and share the same heap, minimizing interoperability overhead and enabling joint optimization.

For an application-owned rule whose source and inputs are trusted, this may be the right trade-off. But not every extension should be able to reach every host capability or share resources with the application. GraalVM lets us add those boundaries without changing how the rule is represented, evaluated, and executed. We begin by limiting what the extension can access.

Constraining host access

The discount rule needs the order total, but nothing else from the host environment. A regular Context already starts with restrictive defaults: only explicitly exported host members are accessible, while native access, process creation, environment access, and host file and socket access are disabled.

With TRUSTED, these restrictions are defaults that application code can relax while configuring the context. CONSTRAINED enforces a restrictive configuration and rejects incompatible options, including those introduced by shared configuration code or later refactoring.

try (Context context = Context.newBuilder("js")
                .sandbox(SandboxPolicy.CONSTRAINED)
                .out(OutputStream.nullOutputStream())
                .err(OutputStream.nullOutputStream())
                .build()) {
    Value discount = context.eval(rule);
    double rate = discount.execute(new Order(120)).asDouble();
    System.out.println(rate);
}

Order.total() remains available because it is explicitly marked with @HostAccess.Export. Other host methods and classes are not exposed automatically. Naming "js" also limits the context to JavaScript; constrained contexts require an explicit list of permitted languages.

The policy prevents the final configuration from enabling broad host access, native access, process creation, system exit, host files or sockets, inherited environment variables, or host class loading. If any part of the application requests an incompatible capability, context creation fails rather than silently weakening the policy.

CONSTRAINED requires explicit guest output and error streams. This example discards both. Applications that retain guest output should use bounded, application-owned streams. The final System.out.println is host application code and is unaffected by this redirection.

The exposed surface is deliberately narrow:

Every exported method remains an application-defined capability. If Order exposed refund() or cancel(), the script could call them. Exported methods must validate guest input and must not expose privileged operations. A sandbox cannot make a dangerous application operation safe.

CONSTRAINED limits the exposure of application code to the extension, but Java and Javascript still share the underlying runtime resources. Restricting CPU and memory usage requires the next level of sandboxing.

Running trusted code on untrusted input

At this point, it is tempting to think that a trusted rule with narrow host access needs no further safeguards. But trusted source does not imply trusted input. An attacker who cannot change the rule may still choose data that drives it into its worst possible behavior. Host-access restrictions do not prevent excessive CPU use, memory allocation, or failures in the guest runtime.

A production rule might parse a coupon, traverse line items, or inspect nested metadata. A crafted coupon can trigger a worst-case parsing path, a huge order can cause large temporary allocations, and an unexpected numeric value can send a loop into a state its author assumed was impossible. Malformed input may even expose a defect in a guest-language library or runtime.

ISOLATED addresses both concerns. In addition to enforcing the capability restrictions of CONSTRAINED, it requires CPU and isolate-heap limits and executes the guest code in a separate runtime instance with its own heap, garbage collector, and JIT compiler.

Isolated execution requires the isolate variant of the Maven language dependency. For JavaScript, use js-isolate with Oracle GraalVM or js-isolate-community with GraalVM Community Edition. See Configuring Polyglot Isolates for dependency details.

try (Context context = Context.newBuilder("js")
                .sandbox(SandboxPolicy.ISOLATED)
                .out(OutputStream.nullOutputStream())
                .err(OutputStream.nullOutputStream())
                .option("engine.MaxIsolateMemory", "64MB")
                .option("sandbox.MaxCPUTime", "2s")
                .build()) {
    Value discount = context.eval(rule);
    double rate = discount.execute(new Order(120)).asDouble();
    System.out.println(rate);
}

The source, evaluation, and invocation remain unchanged. The memory and CPU limits shown above are mandatory for ISOLATED; context creation fails if either is omitted. Their values must be chosen by the application. A CPU-bound execution is canceled when it exceeds its configured budget, while guest allocations are accounted against the isolate heap.

The sandbox setup now looks like this:

By default, the guest runtime runs as an isolate inside the application process. It can also run in an external process when a separate address space and process boundary are required. We will return to that deployment choice later.

The Java API still looks the same, but separate heaps change the lifetime of references that cross between Java and JavaScript. That is the next consequence to consider.

Working with separate heaps

At first, separate heaps appear to make memory ownership simple: host objects live on one heap and guest objects on another. Cross-heap references complicate that picture.

A separate heap gives guest execution its own garbage collector and creates a clear accounting boundary for memory. When Java and JavaScript share a heap, their objects occupy the same memory pool. GraalVM can estimate how much memory a context retains, but that accounting is periodic and its limit may be exceeded before enforcement. It cannot provide a hard guest-only heap ceiling.

An isolate changes that. The engine.MaxIsolateMemory option places a hard cap on the complete guest runtime heap. Guest allocations are accounted against this limit rather than consuming space in the host application heap. This is a limit on the isolate heap, not on every form of native or process memory.

The separate heap does not prevent values from crossing between Java and JavaScript. Objects remain on their owning heap, while references across the boundary are represented by handles behind the scenes. This introduces a problem familiar from distributed garbage collection.

Suppose the discount rule also receives a DiscountLog callback through which it records why a discount was applied:

public final class DiscountLog {

    private String reason;

    @HostAccess.Export
    public void report(Value details) {
        reason = details.getMember("reason").asString();
    }
}

When JavaScript calls log.report({ reason: "large order" }), details is a guest value passed to Java. The implementation copies the required field into a Java String, so the host does not retain a reference into the guest heap.

Without scoped callback values, retaining details in a Java field could create a cross-heap cycle if the guest object referred back to log. The complete cycle might no longer be reachable by the application, yet each collector would still see an incoming reference from the other heap and keep its side alive:

Distributed garbage-collection problems are easy to dismiss because small tests usually finish before retained objects accumulate, and neither heap contains an obvious leak when examined independently. In production, however, cross-heap cycles can accumulate gradually and surface much later as growing isolate heaps, unexpected resource-limit failures, or reduced throughput. The callback that created the cycle may be far removed from the eventual symptom, making the problem particularly difficult to diagnose.

GraalVM avoids the common accidental form of this cycle by scoping guest values passed to exported Java callbacks. ISOLATED enables this behavior by default, as does UNTRUSTED, the policy for untrusted source discussed in the next section. The host can use such a value while the callback runs, but its reference into the guest heap is released when the callback returns:

With scoped callback parameters, details is valid only while report() executes. When the callback returns, the scoped Value is invalidated and its reference into the guest heap is released. Retaining it in a Java field and using it later would result in an IllegalStateException.

If a callback deliberately needs to retain a guest value, it can call details.pin() before returning. Pinning opts that value out of automatic release. It is an explicit lifetime decision and should be used carefully because it can reintroduce a long-lived reference across the two heaps.

The existing Order.total() callback accepts no guest object, so it requires no special handling.

Scoped callback parameters are the main interoperability rule applications need to account for when moving to separate heaps. Context creation, evaluation, and value invocation otherwise work as before.

With host capabilities, runtime failures, and cross-heap references accounted for, we can take the final step: stop trusting the rule source itself.

Running untrusted code

The best-understood example of untrusted JavaScript is the web browser. A browser downloads JavaScript from a website and executes it while assuming that the website may be malicious. The script may try to escape the JavaScript runtime, exploit the JIT compiler, exhaust resources, or misuse every capability available to it. It must not compromise the browser or gain arbitrary access to the local machine.

UNTRUSTED is designed for this adversarial model. In our example, the customer-supplied discount rule plays the role of website JavaScript, while the SaaS application plays the role of the browser.

So far, the application has owned the discount-rule source. Now assume that the source was submitted by a customer, loaded from an external database, or generated by AI. The Source itself must be treated as untrusted:

Source rule = Source.create("js", submittedRule);

Creating a Source only represents the submitted program. It does not validate the program or make it trusted. The sandbox is established when the source is evaluated in an appropriately configured context. Although the API may allow it, running untrusted source under any policy other than UNTRUSTED is unsupported and not covered by the sandbox.

With ISOLATED, we trusted the rule and protected the host from bugs or malicious input. With UNTRUSTED, the attacker controls the source processed by the parser, runtime, and JIT compiler. The attacker can deliberately construct programs that consume resources, exercise unusual runtime paths, or shape the machine code emitted by the compiler.

UNTRUSTED retains the separate runtime, heap, garbage collector, and JIT compiler provided by ISOLATED. It then requires additional resource limits and enables compiler and runtime defenses designed for adversarial guest code:

double applyDiscount(Source rule, Order order) {
    try (Context context = Context.newBuilder("js")
                    .sandbox(SandboxPolicy.UNTRUSTED)
                    .out(OutputStream.nullOutputStream())
                    .err(OutputStream.nullOutputStream())
                    .option("engine.MaxIsolateMemory", "64MB")
                    .option("sandbox.MaxHeapMemory", "32MB")
                    .option("sandbox.MaxCPUTime", "2s")
                    .option("sandbox.MaxASTDepth", "100")
                    .option("sandbox.MaxThreads", "1")
                    .option("sandbox.MaxOutputStreamSize", "64KB")
                    .option("sandbox.MaxErrorStreamSize", "64KB")
                    .build()) {
        Value discount = context.eval(rule);
        return discount.execute(order).asDouble();
    }
}

As with ISOLATED, an UNTRUSTED execution is canceled after the runtime detects that its configured CPU budget has been exceeded. GraalVM reports the failure with a PolyglotException for which isResourceExhausted() returns true. Once a resource limit has canceled a context, that context can no longer execute guest code.

Attacker-controlled source also makes the JIT compiler part of the attack surface. UNTRUSTED blinds constants embedded in generated machine code and randomizes compiled-function entry points, making the compiler output less predictable for JIT-spraying attacks. It also masks memory accesses and inserts speculative-execution barriers where masking is not applicable. Because the guest has its own JIT compiler, these defenses can be applied to guest code without imposing their cost on the host application’s compiler.

One final assumption remains: if an execution was contained successfully, one might consider the result trusted, but it is not. A hostile rule may return -1, NaN, or 1000 without ever escaping the sandbox. The application must verify that the discount is finite and between 0 and 1. The sandbox constrains how the rule executes; it does not decide whether its answer is meaningful.

Under both ISOLATED and UNTRUSTED, the guest runtime runs as an internal isolate inside the application process by default. Applications that require a separate address space and process boundary can use the external isolate mode with engine.IsolateMode=external. The child process has a separate address space and signal domain, so fatal guest failures no longer terminate the host process.

The sandbox limit values in this example are illustrative rather than production defaults. Production limits should be derived from representative workloads; see Configuring sandbox resource limits, including the use of sandbox.TraceLimits.

With the policy and its limits selected, the next decision is which scripts may share an engine.

Sharing code within a security domain

A SaaS application rarely runs one rule for one customer. It may run the same rules and libraries in many execution contexts across requests and tenants. Creating a separate engine for every context would needlessly parse and warm up that code repeatedly.

An explicit Engine defines the scope of code sharing. It owns the code cache: cached Source entries, parsed ASTs, profiling data, and optimized machine code. A Context owns an execution scope's application state, including global variables, guest objects, modules, and context-bound Value instances. Sharing an engine shares code, not application state.

By default, each context creates an implicit engine. An application opts into sharing by creating an explicit engine for a security domain and passing it to each context with Context.newBuilder("js").engine(domainEngine). The engine must be created with the domain's permitted languages, sandbox policy, default streams, and engine-level options such as engine.MaxIsolateMemory. Contexts attached to it must use compatible sandbox settings. The source can then be parsed once, and compilation and warmup can be amortized across contexts. This can reduce startup latency and memory when many contexts execute the same code.

Truffle languages, including Graal.js, implement context-independent code. This means the same JavaScript AST and optimized machine code can execute in different contexts without capturing the global variables or objects of the context that first ran it. This comes with a small peak-performance penalty: type checks, property accesses, and function or method calls cannot specialize as aggressively on context-specific object identities. When the same code runs in many contexts, avoiding repeated parsing and warmup typically outweighs that cost.

A security domain is a group of guest programs for which the application accepts sharing code artifacts and runtime resources. Programs in the same domain may all be untrusted relative to the host without being mutually distrusting. For example, one customer’s rules might share an engine, while rules from customers that must be isolated from one another use separate engines.

All contexts sharing an engine use the engine’s sandbox policy. With isolate-backed execution, they also share the guest runtime, isolate heap, garbage collector, and JIT compiler. The hard engine.MaxIsolateMemory limit therefore applies to the domain's shared isolate. Context limits apply per context and generally accumulate across guest executions in that context. Scripts from different security domains need separate engines.

Bringing sandboxed extensions to production

Sandboxing has been a long-term focus for GraalVM. The Polyglot API, Truffle runtime, and GraalJS that provide its foundation have been used in production for many years. Within Oracle, NetSuite SuiteScript and Oracle Database MLE are longstanding users of these technologies. Picnic also uses GraalVM to run JavaScript and Python business rules from a Java backend, evaluating approximately 38 million rules per day, as described in Extending Java with Python and JavaScript at Picnic.

GraalVM is a good fit when a JVM host application needs to run JavaScript or WebAssembly close to its application data, expose a host API, and execute reusable code in many separate contexts, whether the host runs on the JVM or as a native executable built with Native Image. Native Image builds must include reachability metadata for host members exposed to guest code, as described under Configuring Native Host Reflection. GraalVM is particularly useful when scripts range from application-owned code to source submitted by untrusted users because the same Polyglot API supports progressively stronger capability, resource, and isolation boundaries. The same API can even be used for multiple languages.

In GraalVM 25.1, the sandbox policies support JavaScript and WebAssembly. Sandbox support for pure Python code without native extensions is under development.

GraalVM Community Edition 25.1 makes these sandboxing capabilities available to the broader GraalVM community. We look forward to seeing how developers use them to build, evaluate, and deploy sandboxed scripts. We welcome use cases, questions, and feedback through GitHub and the GraalVM Community Slack.

To get started, see the documentation for embedding languages, Polyglot Isolates, and sandboxing.

Happy sandboxing!

Sandboxing Script Extensions with GraalVM was originally published in graalvm on Medium, where people are continuing the conversation by highlighting and responding to this story.

GraalJS, the high-performance embeddable JavaScript implementation on GraalVM, is here with the latest ECMAScript features!

JavaScript is a core part of modern web development. At Oracle, we use it in multiple ways: to build products and services, to let developers extend our platforms, and to connect applications with Oracle services.

We also participate in moving the language forward. Oracle is part of Ecma International and TC39, the committee that evolves ECMAScript, the standardized language implemented by JavaScript engines.

GraalJS is a key part of that work. It is modern, fast, easy to embed in Java and Kotlin applications, and interoperable with GraalPy and other Graal Languages. Through GraalJS’s support for Node, it can also run Node.js applications, and it uses GraalWasm to implement the WebAssembly JavaScript API.

GraalJS is developed in the open, with source code and community distributions available under the Universal Permissive License (UPL). GraalJS is published on GitHub and Maven Central, and its compatibility work is tested against Test262, the official ECMAScript conformance suite with more than 50,000 tests.

The unique features of GraalJS, such as embeddability and fast interoperability with Java, enable several important use cases in Oracle’s systems. NetSuite is a good example: SuiteScript, its scripting engine that supports sophisticated procedural logic, is powered by GraalJS. For customers and partners developing in SuiteScript, this provides access to the full range of modern JavaScript language features out of the box.

Oracle Database takes the idea of embeddability in another direction. The Multilingual Engine (MLE) in Oracle Database lets developers run JavaScript close to the data, including dynamic snippets and JavaScript modules stored in the database. Under the hood, MLE uses GraalVM’s embedding and Native Image capabilities to bring JavaScript execution into the database environment.

The latest release, GraalJS 25.1, ships full support for ECMAScript 2026, the 17th edition of the ECMAScript standard, and makes it the default language version.

For most applications, no extra configuration is required: the latest standardized JavaScript language and library features are available out of the box. Applications that need to pin a specific ECMAScript version for compatibility can continue to do so with the js.ecmascript-version option.

ECMAScript 2026 Highlights

ECMAScript 2026 standardizes practical additions across numeric computation, iterators, asynchronous data collection, error detection, keyed collections, binary encoding, and JSON processing. These features are available by default in GraalJS 25.1.

• Array.fromAsync() constructs arrays from async iterables, sync iterables, and array-like inputs. It also accepts an optional mapping function applied to each element, and the result is awaited before it is added to the array.
• Iterator.concat() sequences multiple iterator or iterable inputs into one lazy iterator, so iterator-based code can stay composable without allocating intermediate arrays.
• Math.sumPrecise() sums an iterable of floating-point numbers with improved numerical stability and minimal precision loss, especially when values have different magnitudes. For example, Math.sumPrecise([1e16, 0.1, -1e16]) returns 0.1, while naive summation returns 0.
• Get-or-insert APIs for Map and WeakMap return an existing value when one is already present, or provide a default value during retrieval when the key is not already present: getOrInsert() and getOrInsertComputed() on Map.prototype and WeakMap.prototype. These APIs simplify common cache, memoization, and grouping patterns.
• Hex and Base64 string support for Uint8Array adds binary conversion APIs for strings of hexadecimal- and Base64-encoded binary data, including fromBase64(), toBase64(), setFromBase64(), fromHex(), toHex(), and setFromHex().
• More expressive JSON APIs let JSON.parse() revivers access the matched segment of JSON source text for the current value, which is useful to preserve precise numeric values. ES2026 also adds JSON.rawJSON() and JSON.isRawJSON(); JSON.rawJSON() allows validated raw JSON fragments to be embedded during stringification, giving applications fine-grained control over JSON.stringify() output for primitive values. Together, these additions allow serialization of BigInt values and make JSON handling more extensible.
• Error.isError() provides a standard way to test whether a value is an actual error object, instead of relying on less robust cross-realm-sensitive checks such as instanceof Error.

Beyond ECMAScript 2026

GraalJS 25.1 also includes support for selected language features outside ECMAScript 2026. Temporal is available in ECMAScript 2027 mode. Some earlier-stage proposals are available in ECMAScript staging mode, while others use explicit experimental options.

Temporal in ECMAScript 2027 Mode

GraalJS 25.1 completes support for Temporal, with modern date/time APIs such as Temporal.PlainDate for calendar dates and Temporal.ZonedDateTime for time-zone-aware scheduling and arithmetic.

Temporal is not part of ECMAScript 2026, so it is not enabled by default. Use ECMAScript 2027 mode to enable it:

js --js.ecmascript-version=2027 app.mjs

Non-Final ECMAScript Features

GraalJS 25.1 includes support for several proposals that have not been finalized yet. These features are experimental and may still change.

In ECMAScript staging mode, GraalJS 25.1 includes:

• Immutable ArrayBuffers: APIs for creating ArrayBuffers that cannot be mutated, resized, detached, or transferred: transferToImmutable() and sliceToImmutable().
• Joint Iteration: Iterator.zip() and Iterator.zipKeyed() for advancing multiple iterators together and working with positionally aligned values.

To enable ECMAScript staging features, set js.ecmascript-version to “staging”: js --js.ecmascript-version=staging app.mjs.

GraalJS 25.1 also includes additional proposals behind explicit experimental options:

• Explicit Resource Management ( --js.explicit-resource-management): using / await using declarations and disposable resource stacks for deterministic cleanup.
• Import Text (--js.import-text): imports text resources as strings, such as YAML or template files.
• Import Bytes (--js.import-bytes): imports arbitrary files as raw bytes using import attributes, returning a Uint8Array backed by an immutable ArrayBuffer.

Node.js 24

GraalJS 25.1 updates the Node support to Node.js 24.14.1, bringing the Node.js 24.x LTS line into the release alongside ECMAScript 2026 support.

Experimental Web Crypto API Option

GraalJS 25.1 also adds the experimental--js.crypto option to expose getRandomValues() and randomUUID() from the Web Crypto API. Use it with --experimental-options --js.crypto=true app.mjs.

For the full list of GraalJS changes, see the CHANGELOG on GitHub.

Conclusion

GraalJS 25.1 brings the latest JavaScript features to GraalJS by default, while keeping compatibility options available for applications that need them. It also updates to Node.js 24 and includes experimental features for developers who want to try what is coming next.

We would like to thank our contributors and community for the feedback, suggestions, and contributions that went into this release. If you have feedback on GraalJS 25.1 or suggestions for future releases, share them with us on Slack, GitHub, or Twitter.

Now go ahead and try GraalJS 25.1!

GraalJS 25.1: Modern JavaScript on GraalVM was originally published in graalvm on Medium, where people are continuing the conversation by highlighting and responding to this story.

First innovation release 🚀

Today, we’re pleased to announce the release of GraalVM 25.1!

GraalVM 25.1 is the first innovation release to build on GraalVM 25, with 25.2, 25.3, and subsequent releases to follow. This new release train will deliver features and improvements sooner, through smaller, incremental releases that make it easier to try new capabilities and provide feedback.

Meanwhile, the long-term support GraalVM 25.0 release train will continue to receive regular Critical Patch Updates (CPUs), providing the stability that production applications require.

You can already download GraalVM and check the release notes for more details.

This release is packed with new exciting features: even smaller native images, Native Image skill, AI-powered reachability metadata, polyglot sandboxing, and so much more — keep reading to learn about them!

You can also watch the release stream with our favorite features and demos:

Even Smaller Native Images 📦

Native Image is widely used to produce small, self-contained native executables. It does this through sophisticated reachability analysis that includes only the parts of your application you actually need, powerful optimizations from the Graal compiler, and more.

In this release, we further reduce the size of native images. We see an improvement of around 3% across a broad set of benchmarks, with small applications, such as CLI and automation tools, seeing the most significant gains. You can expect even more updates towards reducing image size in the next releases!

This improvement is achieved by reducing metadata stored in the image, making image heap storage more compact, and new more efficient String.format optimization.

As an example, we measured the impact of size optimization on the google-java-format project, which uses GraalVM Native Image to produce compact executables for distribution. The current release contains a linux-x86–64 build of 33.03 MB, while built with GraalVM 25.1 it goes down to 30.74 MB — 6.94% smaller!

Native Image Performance 🚀

Great news: this release introduces a highly-requested by our community feature: G1 GC is now available in Native Image on Darwin/aarch64! This means that you can have the same build setup for native images between your local Darwin AArch64 machine and a Linux-based deployment environment, or have better performance for your applications running on Darwin.

We also introduced a new Serial GC policy, Adaptive2, which uses mark-compact collection in the old generation by default. On average, this policy reduces memory usage and often improves throughput and latency. In our benchmarks, we observe improvements around peak RSS, throughput, and latency, although the exact impact varies by workload. For example, a Micronaut ShopCart application using Adaptive2 shows ~8% lower RSS and 3.8% higher throughput.

1500 libraries in the GraalVM Reachability Metadata Repository! 🤖

Native Image uses a closed-world assumption for AOT compilation. Static analysis can infer a lot, but some behavior is only visible at run time. Reachability metadata fills that gap for dynamic features such as reflection, resources, serialization, JNI, and proxies.

To simplify and automate working with reachability metadata for our users, several years ago we introduced GraalVM Reachability Metadata Repository. The goal was simple: let users share and reuse metadata instead of solving the same compatibility problems in every application. Over the years, we built out the repository together with Spring and Micronaut teams, and other members of the GraalVM community.

This year, with the rise of production-grade AI agents, we saw an opportunity to scale this work. We use a fleet of AI agents and a carefully designed workflow to generate the necessary metadata for thousands of libraries. The workflow starts with Native Image reports, uses tests to exercise dynamic behavior through standard library APIs, generates metadata from observed execution, and verifies the result with Native Image, CI, and human review.

As a result, Native Build Tools now can automatically pull reachability metadata for almost 1500 libraries!

To benefit from the repository, just make sure that your Maven or Gradle project uses Native Build Tools.

Requesting reachability metadata for a new library is as simple as providing its Maven coordinates — follow the instructions on GitHub.

Native Image Skill for AI Agents 🤖

We added a Native Image skill to oracle/skills! This repository is a centralized collection of specialized skills for working with common Oracle technologies, such as Oracle Database, Oracle APEX, GraalVM, Fusion, OCI, and others.

Our skill provides AI assistants with the best practices and practical steps for common Native Image workflows and tasks. By using this skill, an AI assistant can help you:

• Build native executables with the Native Image CLI;
• Configure Native Build Tools for Maven and Gradle projects;
• Set common build options for performance, binary size, monitoring, and security;
• Work with reachability metadata;
• Troubleshoot build failures, runtime differences, class initialization issues, missing metadata, and other issues.

We look forward to your feedback as you try the skill in your projects. You can explore on GitHub, or install from command line:

npx skills add oracle/skills/graal

Dynamic Class Loading in Native Image 🌎

This release includes an early version of Dynamic Class Loading in Native Image. It can be useful for libraries and tools that generate JVM bytecode at run time, and open the door to more plugin use cases, such as loading javac annotation processors dynamically. Good example of such project is for example ByteBuddy — a library commonly used to generate and modify classes at runtime.

To try it, pass -H:+RuntimeClassLoading to your Native Image build.

While Crema is still a work in progress, it includes another step in
that direction: it adds Ristretto — a JIT compiler for runtime-loaded classes. To try it, additionally pass -H:+GraalJITCompileAtRuntime to your Crema build.

Developer Experience Improvements 🛠️

• JFR recordings and heap dumps on Windows: Native Image now supports these diagnostics on Windows, making debugging more consistent across platforms.
• --print-options for native-image: print available build options directly from the tool in table, Markdown, or JSON format. It can be useful for option discovery, docs, and tooling.
• JFR emergency dumps on POSIX: when an out-of-memory error happens while a JFR recording is active, Native Image can preserve the in-memory recording data in an emergency JFR file.
• Runtime collection of conditional reachability metadata: -XX:TraceMetadataConditionPackages helps collect more precise metadata from a native image at run time.
• Simpler tracing-agent filtering: the Native Image agent now applies built-in filters by default. Custom filters can still be passed directly when needed.
• Reachability metadata schema shipped with GraalVM: the schema is now available locally at <graalvm-home>/lib/svm/schemas/reachability-metadata-schema.json, with more detailed validation constraints.
• Portable Native Image bundles: bundle path maps are now portable across platforms, and the bundle format is versioned as 1.0.
• Bundle size warnings: Native Image bundles can now warn when individual files or the total bundle size exceed configured limits.
• -Werror for Native Image: treat warnings as errors, which is useful for CI and stricter build pipelines.

GraalPy 🐍

• GraalPy now includes new -X jit=0|1|2 presets. These presets make it easier to tune GraalPy for different workloads, from startup-heavy applications to throughput-oriented ones. The GraalPy launcher now defaults to the jit=1 preset.
• The GraalPy Native standalone on Linux now uses a lower-footprint Native Image garbage collection configuration. This reduces resident set size (RSS) for many workloads, but may increase startup time and warmup time — we encourage you to try it on your own workloads.
• Java interoperability got several useful improvements. Foreign buffer objects are now treated as Python buffer-compatible binary objects, so APIs such as memoryview, bytes, bytearray, binascii.hexlify, and io.BytesIO work naturally with them. This makes it easier to pass binary data between Python and Java ByteBuffer or ByteSequence objects, with minimal and sometimes zero copies.
• For embedding use cases, GraalPy adds more precise control over execution. New Truffle source options let embedders set the Python optimization level with python.Optimize and run code with a fresh globals dictionary using python.NewGlobals. There is also a new Java backend for pyexpat, useful when running without native access or in multiple-context scenarios. This backend is the default when embedding; the standalone distribution still defaults to native expat.
• GraalPy 25.1 also improves compatibility. The _ctypes module now uses the native CPython version instead of the previous intrinsified implementation, which improves compatibility and reduces the memory footprint of using ctypes. GraalPy also dispatches sys.audit events to hooks registered with sys.addaudithook, including events raised through the PySys_Audit C API.
• Standalone JVM artifacts are no longer released as separate distributions. For standalone deployments, use the GraalPy native artifacts. If you require Java interoperability, use our jbang launcher (jbang graalpy@oracle/graalpython -c "print('hello from GraalPy')") or a custom embedding.

GraalJS and GraalWasm

GraalVM 25.1 also brings important updates for GraalJS, including new ECMAScript support, Node.js updates, new WebAssembly proposals, and more.

• ECMAScript 2026 mode and features are now enabled by default.
• Node.js has been updated to version 24.14.1.
• Temporal support is complete and available in ECMAScript 2027 mode: enable with --js.ecmascript-version=2027
• The new experimental js.crypto option provides getRandomValues() and randomUUID() from the Web Crypto API.
• The stable js.performance option provides performance.now(), timeOrigin, and toJSON() from the Web High Resolution Time API.
• The WebAssembly GC proposal is now implemented and enabled by default! It can be disabled with wasm.GC=false.
• GraalWasm now uses a bytecode-handler-based design for the WebAssembly interpreter, improving interpreted performance on Native Image.
• Standardized WebAssembly features Extended Constant Expressions, Multiple Memories, Relaxed SIMD, and Typed Function References are now enabled by default.

For a detailed list of GraalJS and GraalWasm updates in this release, check the release notes.

Polyglot Runtime

Also new in GraalVM 25.1, the Truffle sandbox is now available in GraalVM Community Edition, giving embedders a practical way to run guest JavaScript or WebAssembly behind a configurable security boundary. Sandboxing is becoming increasingly important as applications look for safe ways to run AI-written code: for example, an application could let users install AI-generated JavaScript plugins while limiting what those plugins can read, how long they can run, and which application APIs they may call. With the Truffle sandbox, applications can restrict host access, file and socket access, native calls, process creation, output, memory, CPU time, statement count, stack depth, and more. We will share more about the Truffle sandbox in upcoming posts, including a deeper technical look and a new project that builds on it to turn prompts into application plugins.

• Starting with Polyglot 25.1, the optimizing Truffle runtime is supported only with GraalVM 25.1 or later, including Oracle GraalVM and GraalVM Community Edition. On standard JDKs down to JDK 21, you can either use polyglot isolates, or the fallback runtime without runtime compilation.
• The JavaScript polyglot isolate now includes support for WebAssembly.
• Language launchers now use --polyglot by default, so you no longer need to pass it explicitly to use other languages in standalones.

For a detailed list of polyglot runtime and Truffle framework updates in this release, check the release notes.

Community and Ecosystem

• After migrating to Native Image, trivago eliminated warm-up and reduced replicas from 43 to 12 for their GraphQL gateway, handling 9,000+ req/s per subgraph. Learn more about their migration process and recommendations.
• Learn how Picnic built a rule engine on GraalVM, where rules are defined in JavaScript or Python and executed by a Java backend, handling 37M evaluations and 2M actions daily.
• A local AWS emulator that starts in 24 ms and uses just 13 MB of idle memory? Learn how Hector Ventura built Floci — free, open-source, and powered by GraalVM!
• GraalVM accepts AI-assisted contributions, while the human contributor remains responsible for reviewing and verifying the submitted change;
• Micronaut 5 was released, moving to a Java 25 and GraalVM 25.0.3 baseline.
• Quarkus 3.35 offers an out-of-the-box PGO integration: enable it with quarkus.native.pgo.enabled=true, and use your existing integration tests for the profiling workflow.

Conclusion

We’d like to take this opportunity to thank our amazing contributors and community for all the feedback, suggestions, and contributions that went into this release.

If you have feedback for this release or suggestions for features that you would like to see in future releases, please share them with us on Slack, GitHub, or LinkedIn.

Now go ahead and try the new GraalVM! 🚀

— the GraalVM team

GraalVM 25.1 is here! 🎉 was originally published in graalvm on Medium, where people are continuing the conversation by highlighting and responding to this story.

Software is moving faster than ever, fueled by AI and rapidly evolving developer tools. To keep pace and get new features and improvements into your hands sooner, we are accelerating the GraalVM release schedule. We are introducing monthly feature releases while continuing to provide quarterly Critical Patch Updates (CPUs) and maintaining one stable release train per major version.

What this means moving forward:

• Oracle GraalVM 25.0 will continue to receive security and minor bug fixes and remains the stable release train.
• GraalVM 25.1+ will provide monthly feature releases for users who want new features sooner. We intend to ship 25.1 in June 2026, followed by 25.2, 25.3, and subsequent releases in the months that follow.

What’s changing

• GraalVM Community Edition previously shipped feature releases every six months, with each receiving two quarterly CPUs before being superseded by the next feature release. Going forward, GraalVM Community Edition will switch to monthly feature releases, incorporating CPUs when they are available each quarter.
• Feature releases for both Oracle GraalVM and GraalVM Community Edition will now ship monthly on the 25.1+ release train. Feature releases are fully tested to ensure stability.

What stays the same

• Quarterly CPUs remain aligned with Oracle and OpenJDK schedules, and all active releases receive the relevant security baseline.
• Weekly Early Access (EA) builds will continue be made available to provide a channel for pre-GA feedback.

Why we’re doing this

Monthly releases reduce the time from idea to impact. Smaller, more frequent drops make it easier for you to try features and provide actionable feedback, which helps us iterate faster. The ecosystem around AI-enhanced development and runtime optimization evolves weekly, and our cadence should reflect that reality. At the same time, security updates remain predictable through quarterly CPUs aligned with the broader Oracle and OpenJDK ecosystem.

Schedule for adopting new features for GraalVM languages

We pick up new features for GraalVM languages once the language is stabilized and starts seeing adoption from the library ecosystem. For Python, this generally means we support a Python version when it enters the security-fix phase (yellow) in the release chart below. The current supported version of Python in GraalVM is Python 3.12, which entered yellow in 2025. Python 3.13 will be supported in 2026.

For JavaScript, a new ECMAScript standard is generally published each June, with support in GraalVM implemented within a few months. This will continue.

The Java library ecosystem generally does not support anything other than Java LTS releases, so as previously announced, there are no plans for GraalVM releases of JDK 26, 27, or 28. GraalVM will track upstream changes and plans to provide Java 29 support shortly after its release.

Understanding release numbers

GraalVM continues to follow the JDK version numbering scheme described in JEP 223 (MAJOR.MINOR.SECURITY). The MAJOR number indicates the Java language specification baseline. The MINOR number indicates the feature release train, such as 25.1, 25.2, and so on. The SECURITY number indicates the CPU level from the underlying JDK update, for example, .3 for April 2026.

What this looks like on the calendar

Oracle GraalVM 25 LTS

Updates for Oracle GraalVM 25 (LTS) continue to be released on the regular quarterly CPU schedule. For example, in 2026 there are four CPU releases:

• January 20th: 25.0.2
• April 21st: 25.0.3
• July 21st: 25.0.4
• Oct 20th: 25.0.5

GraalVM feature releases

Monthly features releases for Oracle GraalVM and GraalVM Community Edition follow the same minor feature/security level numbering. Each quarter, a feature release will include the latest JDK Critical Patch Updates (CPU), which is reflected in version’s SECURITY digit. For example:

• June 2026 (Feature): 25.1.3
• July 2026 (Feature + CPU): 25.2.4
• Aug 2026 (Feature): 25.3.4
• …

See the Release Calendar for exact CPU days and planned versions: https://www.graalvm.org/release-calendar/

What’s coming in monthly feature releases

We will use the monthly 25.1+ feature line to deliver incremental capabilities across Native Image and language runtimes. The following highlights are in focus.

Truffle — New Bytecode Interpreters are rolling out to GraalPy, GraalJS, and GraalWasm. These interpreters improve warmup performance and reduce memory footprint significantly before JIT compilation is performed. See https://github.com/oracle/graal/blob/master/truffle/docs/bytecode_dsl/BytecodeDSL.md

GraalPy (Python) — the major focus is on the bytecode interpreter and other optimizations to improve Python warmup as well as to reduce the cost of native method crossing. We continue to improve ecosystem compatibility and JVM interop (for example, support for using `java.util.List` as a Python list object). See https://www.graalvm.org/python/

Native Image — Layers improves deployment by enabling layered native images with shared base layers that include the JDK, frameworks, and libraries. These layers can be mapped and reused to reduce memory usage and improve container efficiency. See https://github.com/oracle/graal/issues/7626 for more information.

Native Image — Crema enables an “Open World” model that supports dynamic class loading and execution at run time. It adds a bytecode interpreter and JIT compiler for classes loaded dynamically on top of an AOT compiled base layer. See https://github.com/oracle/graal/issues/11327 for details.

Native Image — Terminus makes the native-image tool self-hosting so the tool itself runs natively. It relies on a strong separation of host and guest heaps via Espresso and aims to deliver faster and more portable builds. See https://github.com/oracle/graal/issues/12236 for more information.

Native Image — Web Image targets WebAssembly to produce Wasm modules, plus a JavaScript wrapper, so JVM applications can run in browsers or in Node.js. See https://www.graalvm.org/latest/reference-manual/web-image/ for details.

GraalJS (JavaScript/Node) — modern ECMAScript support and first class embedding in polyglot scenarios. See https://www.graalvm.org/latest/reference-manual/js/

GraalWasm (WebAssembly) — execute and embed Wasm modules inside JVM applications for safe, high performance plugin architectures. See https://www.graalvm.org/webassembly/docs/

Guidance for different users

• Production applications should remain on the 25.0 LTS release train and upgrade to the latest CPU each quarter.
• Applications on feature trains can adopt monthly feature releases on their own schedule to pick up new capabilities, but for maximum security should always upgrade to a release with the latest CPU.
• Framework, library, and tooling authors should find monthly releases incremental and predictable. We will pre-announce noteworthy changes in EA and we welcome coordination during CPU weeks.
• Early adopters are encouraged to try EA builds for upcoming monthlies to validate changes against their workloads and to provide feedback earlier.

Frequently asked questions

• How do security fixes flow into monthly releases ?
  For each release, the third version digit (i.e., the SECURITY digit) matches the JDK CPU level. After each CPU Tuesday, the next monthly feature release carries that CPU level, for example 25.2.4 in July 2026.
• How long is each monthly 25.1+ feature release supported?
  Each feature release is superseded by the next one. We do not backport fixes to older feature releases, so users should upgrade forward.
• Will there be backports to earlier monthly releases?
  No, users should upgrade forward to the latest monthly release to receive bug fixes and security patches. However, Oracle GraalVM 25.0 customers continue to receive support per policy on LTS lines.

All aboard!

We all need to move faster, so join us on the new high-speed GraalVM release train!

Try Early Access builds and tell us what works and what does not. Adopt monthly feature releases to unlock improvements sooner. Stay current on CPUs for the latest security fixes.

Accelerating the GraalVM Release Train was originally published in graalvm on Medium, where people are continuing the conversation by highlighting and responding to this story.