enhancement
major
minor
major
minor
major
#29645
TL-Script: @SideEffectFree an Funktionen aus TLScriptFunctions wird ignoriert, da der Annotation die Laufzeit-Retention fehlt
Problem
TL-Script-Funktionen, die als public static-Methoden einer TLScriptFunctions-Unterklasse definiert sind (z.B. MathFunctions, BinaryFunctions, AccountFunctions, ObjectFunctions, JobFunctions, HtmlFunctions, FlowFactory), deklarieren mit @SideEffectFree (optional canEvaluateAtCompileTime = true), dass sie keine Seiteneffekte haben. Rund 117 Methoden tragen diese Annotation.
Die Annotation com.top_logic.model.search.expr.config.operations.SideEffectFree hat jedoch keine @Retention(RUNTIME). Ohne Angabe gilt RetentionPolicy.CLASS: die Annotation steht in der Class-Datei, ist per Reflection aber nicht sichtbar. TLScriptMethod.Builder liest sie mit _method.getAnnotation(SideEffectFree.class) und erhält immer null. Damit gilt:
- TLScriptMethod.isSideEffectFree() liefert für jede solche Funktion false.
- canEvaluateAtCompileTime ist immer false; ConstantFolding wertet keine dieser Funktionen mit konstanten Argumenten zur Übersetzungszeit aus.
- SearchExpressionCompiler.compile hält jedes Skript, das eine dieser Funktionen aufruft, für seiteneffektbehaftet (HasSideEffects) und überspringt für das ganze Skript die strukturellen Vereinfachungen (TRANSFORMS: Umformungen boolescher Ausdrücke, Herausziehen von Vereinigungen aus Filtern). (Das Herausziehen unabhängiger Teilausdrücke, SubExpressionPullOut, ist unabhängig davon wegen #22261 derzeit abgeschaltet.)
Die Deklaration hat also nie gewirkt; Skripte funktionieren korrekt, werden aber schlechter optimiert als beabsichtigt.
Gefunden bei der Umsetzung von #29639 (TestUsesSecurity: der Test, dass eine Funktion mit Sicherheits-Flag nicht gefaltet wird, ist nur deshalb trivial grün).
Lösung
- SideEffectFree hat @Retention(RetentionPolicy.RUNTIME) und @Target(ElementType.METHOD). Die Dokumentation der Annotation beschreibt den Vertrag: die Funktion verändert keinen Zustand – keine persistenten Änderungen, keine Änderung ihrer Argumente oder anderer bestehender Objekte, keine Registrierung oder Protokollierung; Lesen (Datenbank, Sitzung, aktueller Benutzer) und das Erzeugen eines neuen Ergebnisobjekts ist erlaubt. canEvaluateAtCompileTime = true nur für eine reine Funktion ihrer Argumente mit unveränderlichem Ergebnis.
- Alle annotierten Methoden wurden geprüft. MathFunctions, BinaryFunctions, ObjectFunctions, AccountFunctions, JobFunctions und HtmlFunctions halten den Vertrag ein.
- FlowFactory (com.top_logic.react.flow.server und com.top_logic.graphic.blocks.server): Die Annotation wurde bei allen Funktionen entfernt, die ein Argument in das Ergebnis einhängen (Eltern-Verweis setzen, Kind-Listen) oder verändern (toSvg layoutet das übergebene Diagramm, gantt vergibt IDs an die übergebenen Zeilen) – 35 bzw. 25 Funktionen. Sie bleibt nur an Funktionen mit reinen Wert-Argumenten (text, empty, image, point, ganttEdge). Das Verhalten dieser Funktionen bleibt damit unverändert.
- Die reinen Funktionen aus MathFunctions (alle außer mathRandom()) haben canEvaluateAtCompileTime = true und werden mit konstanten Argumenten zur Übersetzungszeit ausgewertet. Ein Aufruf mit konstanten, aber ungültigen Argumenten scheitert damit bereits beim Übersetzen des Skripts.
- Eine Funktion mit einem @UsesSecurity-Parameter (#29639) wird weiterhin nie zur Übersetzungszeit ausgewertet.
- Test TestSideEffectFree: eine TLScriptFunctions-Funktion mit @SideEffectFree liefert isSideEffectFree() == true, eine ohne Annotation false; eine mit canEvaluateAtCompileTime = true wird bei konstanten Argumenten gefaltet, eine ohne das Flag und eine mit Sicherheits-Parameter nicht; mathSqrt(4) wird gefaltet, mathRandom() nicht.
Migration
Eigene TL-Script-Funktionen (statische Methoden in TLScriptFunctions-Klassen), die mit @SideEffectFree annotiert sind, prüfen: Die Annotation wird jetzt ausgewertet. Methoden mit Seiteneffekten dürfen sie nicht tragen.