Summary

Provide an API to allow users to supply explicit max stack and locals counter values when building a Code attribute with ClassFile API.

Problem

Some performance-sensitive bytecode generation wishes to avoid counter calculation in class file generation.

For example, in the pattern-matching switches in the JDK, the code has a lot of branching, making the counter calculation slow; however, the counter values are straightforward - the stacks is at max 3 for enum label matching, and the locals is just those passed through the method type.

Recent optimization of switches already makes use of an internal API. This API can be made public, with detailed behavior specification and argument checks.

Solution

Add a new API, withExplicitStackAndLocals, to CodeBuilder. The name choice emphasizes the explicit aspect, and the order of stack and locals values (stack comes first).

This API is only effective is DROP_STACK_MAPS is on, otherwise the stack and locals are simple byproducts of stack map generation.

This API is only effective if a CodeBuilder builds a whole Code attribute that is not later teared apart by transformations. These considerations are also specified.

To ensure integrity, the argument validation happens even if the call would have been no-op.

An alternative approach considered and rejected was to model this with a new CodeElement. These values are extremely sensitive to any change in the code array, and are thus never suitable to be modeled in a code transformation, or as part of a code model subject to transformation. In addition, it would pollute the pattern matching switches used for code transformation. Thus, a simple new API with documented strict restrictions is chosen instead.

Specification

    /**
     * Provides this builder with explicit {@code max_stack} and {@code
     * max_locals} values when {@link StackMapsOption#DROP_STACK_MAPS} is set.
     * No automatic counting for the two max values will be done; the resulting
     * {@code Code} attribute will instead use the provided values.
     * <p>
     * This call does not affect the two max values if any of the following is
     * true:
     * <ul>
     * <li>{@code DROP_STACK_MAPS} is not set;
     * <li>this builder does not build a complete {@code Code} attribute;
     * <li>this builder's output is redirected to a {@link CodeTransform};
     * <li>the built {@code Code} attribute is subsequently inflated in a
     * transformation;
     * </ul>
     * <p>
     * This call always validates the provided max values.
     *
     * @param maxStack the max stack slots used by this method body
     * @param maxLocals the max local variable slots used by this method body
     * @return this builder
     * @throws IllegalArgumentException if any of the values is not a {@code u2}
     * @since 25
     */
    CodeBuilder withExplicitStackAndLocals(int maxStack, int maxLocals);