enhancement
major
minor
major
minor
major
#29645
TL-Script: The @SideEffectFree annotation on functions from TLScriptFunctions is ignored because the annotation lacks runtime retention.
Problem
TLScript functions defined as public static methods of a TLScriptFunctions subclass (e.g., MathFunctions, BinaryFunctions, AccountFunctions, ObjectFunctions, JobFunctions, HtmlFunctions, FlowFactory) use the @SideEffectFree annotation (optionally with canEvaluateAtCompileTime = true) to indicate that they have no side effects. Approximately 117 methods carry this annotation.
However, the annotation `com.top_logic.model.search.expr.config.operations.SideEffectFree ` does not have `@Retention(RUNTIME)`. Without a specification, `RetentionPolicy.CLASS` applies: the annotation is present in the class file but is not visible via reflection. TLScriptMethod.Builder reads it using _method.getAnnotation(SideEffectFree.class) and always returns null. Therefore:
- TLScriptMethod.isSideEffectFree() returns false for every such function.
- `canEvaluateAtCompileTime ` is always ` false`; ConstantFolding does not evaluate any of these functions with constant arguments at compile time.
- SearchExpressionCompiler.compile treats any script that calls one of these functions as having side effects (HasSideEffects) and skips the structural simplifications for the entire script (TRANSFORMS: transformations of Boolean expressions, extracting unions from filters). (The extraction of independent sub-expressions, SubExpressionPullOut, is currently disabled regardless of this due to #22261.)
So the declaration never took effect; scripts work correctly but are optimized less effectively than intended.
Discovered during the implementation of #29639 (TestUsesSecurity: the test verifying that a function with a security flag is not folded is only trivially green for this reason).
Solution
- SideEffectFree has @Retention(RetentionPolicy.RUNTIME) and @Target(ElementType.METHOD). The annotation’s documentation describes the contract: the function does not modify any state—no persistent changes, no modification of its arguments or other existing objects, no registration or logging; reading (database, session, current user) and creating a new result object are permitted. canEvaluateAtCompileTime = true only for a pure function of its arguments with an immutable result.
- All annotated methods have been verified. MathFunctions, BinaryFunctions, ObjectFunctions, AccountFunctions, JobFunctions, and HtmlFunctions comply with the contract.
- FlowFactory (com.top_logic.react.flow.server and com.top_logic.graphic.blocks.server): The annotation was removed from all functions that append an argument to the result (set parent reference, child lists) or modify it (toSvg lays out the passed diagram, gantt assigns IDs to the passed rows)—35 and 25 functions, respectively. It remains only on functions with pure value arguments (text, empty, image, point, ganttEdge). The behavior of these functions therefore remains unchanged.
- The pure functions from MathFunctions (all except mathRandom()) have canEvaluateAtCompileTime = true and are evaluated at compile time with constant arguments. A call with constant but invalid arguments therefore fails as early as the script’s compilation.
- A function with an @UsesSecurity parameter(#29639) is still never evaluated at compile time.
- Test TestSideEffectFree: a TLScriptFunctions function with @SideEffectFree returns isSideEffectFree() == true; one without the annotation returns false; one with canEvaluateAtCompileTime = true is folded when given constant arguments, while one without the flag and one with a security parameter are not; mathSqrt(4) is folded, mathRandom() is not.
Migration
Check your own TLScript functions (static methods in TLScriptFunctions classes) that are annotated with @SideEffectFree: The annotation is now evaluated. Methods with side effects must not carry this annotation.