Repository navigation
Combat 2.1d: Compile math expressions once and evaluate with variables - #194
Merged
Merged
Conversation
Add Evaluator.compile(String, String...) returning an immutable, thread-safe CompiledExpression. The expression is parsed once with the bundled Javaluator grammar and evaluated from a tree without parsing or allocating per call. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FaEyTqc8jf3RR3v7Fz7SHm
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Evaluator.eval(String, int)takes no variables and parses the string on every call. Underneath, Javaluator'sDoubleEvaluator.evaluate(String, context)supports variables but also tokenizes and parses every time. Formax(d/5, d - 4*x/max(1, t+8))that is about 3,400 ns per call (about 4,300 ns in the original measurement), against about 4 ns for the same arithmetic in Java. That is too slow for a combat hot path. Needed by magemonkeystudio/divinity#371, which moves damage formulas into a config file and evaluates them on every hit.API
Evaluator.compile(String expression, String... variables)parses once and resolves each variable to its position in the name list. It throwsIllegalArgumentExceptionwith a one-line message that names the expression and the cause (with the position where the parser has one) for: a syntax error, an unknown variable or function, mismatched brackets, a wrong argument count, and a variable name that is unusable. Names that are a function, a constant, a number, empty, contain whitespace or an operator/bracket/comma, arenullor are repeated are rejected.CompiledExpression.eval(double...)is immutable and thread safe. It throwsIllegalArgumentExceptionif the number of values differs from the number of names. NaN and infinity are returned as they are.getSource()andgetVariableNames()(unmodifiable list).Evaluator.eval(String, int)and all Javaluator classes are untouched. No visibility changes were needed in the bundled Javaluator classes.eval. The only array is the varargs array at the call site, which javac creates and the JIT usually scalar-replaces. A caller can pass its owndouble[]to avoid it.codex-apibuilds with<release>14</release>on Spigot 1.16.5 API. The new code uses nothing newer than Java 8 APIs and the repo's Lombok (@Getter,@ToString).How it reuses Javaluator
ExpressionCompilerextendsAbstractEvaluator<ExpressionNode>, withDoubleEvaluator.getDefaultParameters(). The values the parser pushes are tree nodes instead of doubles. So the tokenizer, operator precedence and associativity, unary minus guessing, bracket matching, argument-count checks, and the constant, operator and function tables are Javaluator's own, not a second grammar. Only the meaning of each operator and function is written out again (copied branch by branch fromDoubleEvaluator). Number literals go through the sameNumberFormat(Locale.US)parse asDoubleEvaluator.toValue.Equivalence guarantee and its limits
For every expression both accept,
CompiledExpressionreturns the same double asDoubleEvaluator.evaluatewith aStaticVariableSet(compared withDouble.doubleToLongBits). Limits:DoubleEvaluatorthrows when a function returns NaN (for examplesqrt(-1)). The compiled form returns NaN there, as requested. If such an inner NaN is later absorbed (for exampleround(NaN)is 0), the compiled result is that finite number, whileDoubleEvaluatorthrows. Tests only compare whereDoubleEvaluatorgives a result.random()gives a new value per call, as inDoubleEvaluator.2^-1is rejected by both, and^is left associative.DoubleEvaluatorfails at compile time as "unsupported" until the compiled form learns it. Tests iterate over all functions, constants and operators ofDoubleEvaluatorto catch that.Benchmark
ExpressionBenchmark(a harness insrc/test, run withmain, one mode per JVM, 15 rounds, median). JDK 21.0.12, 4 vCPU container, so treat as indicative.DoubleEvaluator+StaticVariableSet)CompiledExpression.evalCompiled is about 99x faster than string evaluation, so the 20x target is met. It is about 10x slower than hand-written Java. A short non-timing pass runs in the build and checks that the three give identical sums.
Tests (
mvn -DskipNms -pl codex-api,codex-core -am test, JDK 21, exit 0)codex-api 355 run (54 before, +301 new), codex-core 13; 0 failures, 0 errors, 0 skipped.
Break-it checks (each applied, test suite run, then reverted; the tree is identical to the committed one)
/made right associative (parser operator swapped)b - a,b / a,pow(b, a))Decisions for review
eval(double...)is the only entry point. If the call-site varargs array shows up in profiles, fixed-arity overloads are easy to add.Generated by Claude Code