Add documentation for analysis metrics

2026-02-22 18:41:27 +01:00
parent 2e8d5284c2
commit 229ca3eefa
1 changed files with 49 additions and 0 deletions
@@ -0,0 +1,49 @@
+# Erweiterungen für NodeMetrics und Analyse-Strategie
+
+Durch die `NodeMetrics`-Dekoration können wir Daten sammeln, die entweder den **Optimizer steuern** oder dem **Linker/VM** bei der effizienten Ausführung helfen. Da der Optimizer den AST massiv verändert, müssen wir zwischen zwei Analyse-Phasen unterscheiden.
+
+## Die Multi-Pass Strategie
+
+1.  **Pre-Optimization Analysis (Pass 1):** Sammelt Heuristiken, um Optimierungen (Inlining, Folding) überhaupt erst zu ermöglichen oder zu begrenzen.
+2.  **Optimizer:** Transformiert den Baum (Inlining dupliziert Code, DCE löscht Code).
+3.  **Post-Optimization Analysis (Pass 2):** Berechnet die finalen, exakten Fakten für das Backend (VM/Linker), basierend auf dem "geschrumpften" Baum.
+
+---
+
+## 1. Steuerungs-Metriken (Pre-Optimization)
+*Helfen dem Optimizer, Entscheidungen zu treffen.*
+
+### A. Estimated Complexity Score
+*   **Was:** Anzahl der Knoten im AST-Zweig.
+*   **Nutzen:** Inlining-Budget. Statt fixer Tiefe wird nach Größe entschieden: "Inline diese Funktion nur, wenn sie < 20 Knoten hat."
+
+### B. Initial Mutation Status
+*   **Was:** Wird eine Variable (Local/Global) jemals mit `Set` verändert?
+*   **Nutzen:** Wenn nein, kann der Optimizer sie wie eine `const` behandeln und den Wert überall dort einsetzen, wo sie gelesen wird (Aggressive Inlining).
+
+### C. Purity (Bereits implementiert)
+*   **Nutzen:** Erlaubt Constant Folding und das Entfernen von ungenutzten Aufrufen (DCE).
+
+---
+
+## 2. Backend-Metriken (Post-Optimization)
+*Werden nach der Optimierung neu berechnet, um der VM/Linker Fakten zu liefern.*
+
+### A. Final Usage Counts (Dead Code Elimination)
+*   **Was:** Wie oft wird eine Funktion/Variable im *finalen* Code noch referenziert?
+*   **Nutzen:** Globale Funktionen, die nach dem Inlining nirgends mehr aufgerufen werden, können vom Linker komplett aus dem Environment entfernt werden.
+
+### B. Escape-Analyse (Closure-Optimierung)
+*   **Was:** Verlässt eine Lambda-Instanz ihren Erzeugungs-Scope (z.B. als Rückgabewert)?
+*   **Nutzen:**
+    *   **Stack vs. Heap:** Nicht-escapende Lambdas können von der VM auf dem Stack (oder in einem Pool) verwaltet werden, statt teure Heap-Allocations für das `Closure`-Objekt auszulösen.
+    *   **Direct Call:** Aufrufe solcher Lambdas können zu direkten Sprüngen/Calls optimiert werden.
+
+### C. Resource Requirements
+*   **Was:** Maximale Stack-Tiefe, Anzahl benötigter Register/Slots.
+*   **Nutzen:** Die VM kann beim Aufruf exakt den benötigten Speicher reservieren, ohne dynamisch wachsen zu müssen.
+
+---
+
+## Fazit
+Einige Werte (wie `UsageCount` oder `Complexity`) sind vor der Optimierung nur Schätzungen, da der Optimizer sie durch Code-Duplikation (Inlining) oder Löschung (DCE) verändert. Erst der zweite Analyse-Pass nach dem Optimizer liefert die "Wahrheit", die für Backend-Optimierungen wie die Escape-Analyse kritisch ist.