Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 155 additions & 0 deletions docs/compile-time-work.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
# Compile-time work: state and how to carry on

Working notes for the compile-time optimisation of tslang itself, started 2026-11-15. Read this to
pick the work up in a new session. User-facing numbers are in [performance.md](performance.md#compile-time).

## 1. Where it stands

The compiler took a time that grew much faster than the source for several kinds of program. Each
case had the same root: something done once per global, call or class that scanned the whole
module. The fixes replace the scan with a table, and every table is checked against the scan it
replaces (section 4).

Merged:

| PR | What |
| --- | --- |
| #862 | The last global is found by scanning the module's top level, not every function body. `LLVMGlobalsIndex` for the LLVM lowering pass: names of LLVM globals and the last global of each kind. |
| #863 | The comdat table is first in the module. `--mlir-timing` works. |
| #864 | MLIR generation remembers each module's last global (`MLIRGenImpl::lastGlobalOfModule`). |

Open: PR #865, branch `perf-compile-time-4`.

| Commit | What |
| --- | --- |
| `8f303db6` | `StackEscapeFacts` looks functions up in a table. |
| `5254b577` | `LLVMGlobalsIndex::lookupSymbol`: the callee of a call is found from a table of the symbols the module has before the conversion. |
| `fea78525` | An enum's member dictionary is made once, not after every member. |

Also on `perf-compile-time-4`, after those three (see `git log`; all went through section 5):

- **Bounded comdat tables** (`addComdatSelector`, `COMDAT_TABLE_SELECTORS` in `LowerToLLVM.cpp`;
`comdatTable` in `LLVMGlobalsIndex.h`). Translation to LLVM IR for 2,000 generic instances:
1.8 s -> 0.5-0.7 s.
- **Symbols the lowering makes are tabled** (`createSymbol`, `lookupOwnSymbolAs`, `createdSymbols`
in `LLVMGlobalsIndex.h`; 14 lookups and 17 creations routed in `OwnershipRoutineLogic.h`,
`ConvertLogic.h`, `LLVMCodeHelperBase.h`, `LLVMCodeHelper.h`, `LowerToLLVM.cpp`). A first version
treated every name missing from the tables as absent from the module; the check caught `puts`,
which MLIR's own `cf.assert` lowering declares. The rule is now: a miss is final only for names
the lowering itself invents (`ownName`), otherwise the scan decides. LLVM lowering of 2,000
interfaces: 2.0 s -> 1.4 s.
- `tslang/benchmarks/compile-time/` (the scripts of section 2) and this document.

Figures, object file, no optimisation, `--no-default-lib`, Windows x64, Release compiler:

| Input | At the start | Now |
| --- | --- | --- |
| 2,000 classes of 5 lines | 99.9 s | 2.5 s |
| 8,000 classes | not measured (4,000: 19.7 s after #862) | 11.9 s |
| 2,000 instances of a generic class | 16.4 s | 6.0-7.0 s |
| 2,000 interfaces with a class and a use each | 10.9 s | 7.3-8.7 s |
| 2,000 classes overriding a base method | 3.3 s | 2.4 s |
| an enum of 2,000 members and a switch | 1.8 s | 0.3 s |
| 2,000 functions of 5 lines | 1.8 s | 1.7 s |

## 2. How to measure

**`--mlir-timing`** prints the time of each stage (MLIR generation, every MLIR pass, translation
to LLVM IR, LLVM optimisation, code emission) for any `--emit`. This is the number to trust.

**`tslang/benchmarks/compile-time/shapes.ps1`** generates 14 program shapes at growing sizes and
prints the time and the growth from one size to the next. Linear is about 2.0x for twice the
source; 3x and more means something quadratic.

```
pwsh tslang/benchmarks/compile-time/shapes.ps1 # all shapes, n = 500, 1000, 2000
pwsh tslang/benchmarks/compile-time/shapes.ps1 -Only interfaces -Stages # which stage grows
```

**`tslang/benchmarks/compile-time/profile.ps1 <file.ts>`** samples call stacks of the Release
compiler (relinked with symbols into `out/`, the build directory untouched) and prints the hot
functions. Use it to find the code inside a stage, not to compare stages: it takes fewer samples
where stacks are deep, and it once showed a lookup at 31% that was 5% of the wall time. A
per-function pass runs on a worker thread; pass `-Flags --mlir-disable-threading` to see it.

The suite's largest test is 1,500 lines and shows none of this. Only generated inputs do.

## 3. What is left, with the cause of each

Measured with all of the above, n = 1,000 -> 2,000. Timings of the larger inputs moved by 10-15%
between runs on the development machine, and at n = 2,000 even code emission (LLVM's, linear)
came out at 2.8x on these two shapes, so read 2.5-2.9x here as "about linear, plus memory":

| Shape | Total | Growth | Where |
| --- | --- | --- | --- |
| interfaces | 2.8 -> 8.7 s | 3.1x | MLIR generation 0.9 -> 3.2 s (3.6x) is the one clear case; LLVM lowering 0.46 -> 1.36 s (2.9x); `OwnedReturnConsumptionPass` and `StackPromotionPass` 0.04 -> 0.2 s (4-5x, small) |
| one function of n `if` statements | 0.65 -> 1.7 s | 2.7x | `TypeScriptToAffineLoweringTSFuncPass` 0.23 -> 0.89 s (3.9x) |
| generics | 2.8 -> 7.0 s | 2.5x | nothing stands out; every stage 2.1-2.8x |
| inheritance, classes | | 2.3x | nothing stands out |

**Interfaces, MLIR generation.** `mlirGenNullInterfaceVTable` (`MLIRGenInterfaces.cpp`) makes one
throwing stub per interface method through `mlirGenThrowingMethodStub`, which asks
`theModule.lookupSymbol<FuncOp>(stubName)` before and after: the first is a miss and scans the
module. `INSTANCEOF_NONE_NAME` is looked up for every vtable and the function is pushed at the
*end* of the module, so each lookup scans all of it. `createGlobalVariable` still scans after a
dummy run made a global (the entry of `lastGlobalOfModule` is dropped then). A fix needs a symbol
table for MLIR generation that survives its erases: `funcOp.erase()` in about eight places,
`GenContext::clean` for dummy runs, and the temp and discovery modules. Count the creation and
erase sites of `mlir_ts::FuncOp` first; if they are few, the pattern of `lastGlobalOfModule` (drop
the entry wherever it can go stale, check against the scan) applies.

**One very large function.** The `IfOp` lowering in `LowerToAffineLoops.cpp` calls
`rewriter.splitBlock`. Under a conversion rewriter that moves the rest of the block one operation
at a time, each with a recorded rewrite, so n sequential `if`s move n^2/2 operations. Options, none
tried: lower the `if`s of a block last to first, so each split moves little; or build the
continuation block once per region instead of splitting at every `if`. Upstream's SCF-to-CF has
the same shape.

**Not looked at:** `OwnedReturnConsumptionPass` and `BorrowFactsExportPass` showed 4-5x growth on
some shapes but small absolute times (0.2 s); the canonicalizer runs grow 2.3-2.6x; `-mm=rc` and
`-mm=own` were only timed on classes; no shape uses the default library; nothing was measured on
Linux.

## 4. The rules that keep the tables honest

Every table answers a question a scan used to answer, and must give the same answer.

- **`TSLANG_VERIFY_LLVM_GLOBALS_INDEX=<file>`** makes the compiler ask the scan too, append any
difference to the file and use the scan's answer. It covers `LLVMGlobalsIndex` (global lookup,
last global, symbol lookup) and `lastGlobalOfModule`. After a change to any of them: run the
whole suite with it set, and the file must not exist afterwards. It has caught two wrong
versions that the plain suite's IR comparison would also have shown, and one (`puts`) that it
would not have.
- **LLVM globals** made during the conversion go through `LLVMCodeHelperBase::createGlobal`;
other symbols through `LLVMGlobalsIndex::createSymbol`. A grep for `create<LLVM::GlobalOp>`,
`create<LLVM::LLVMFuncOp>` and `create<func::FuncOp>` under `LowerToLLVM` should find only the
wrappers and the code that runs after `applyFullConversion`.
- **Rollback.** The conversion driver erases what a failed pattern created. The index is the
conversion's listener (`notifyPatternEnd` arrives when a pattern fails, in MLIR 22.1.8) and
forgets its pointers when a pattern that created something fails. Pointers to symbols that
existed before the conversion are safe until it ends.
- **A miss is final only for the lowering's own names.** MLIR's patterns create symbols too.
- **In MLIR generation** the remembered global of a module is dropped where a global or a module
is erased, for dummy-run globals, and around `MLIRRTTIHelperVC` (`RttiGlobalsScope`), which
makes globals itself.
- A cheaper comparison inside a scan does not help: the cost is walking the operation list.

## 5. Verifying a change

1. Build Release: `cmake --build . --config Release --target tslang -- /m:6` in
`__build/tslang/windows-msbuild-2026-release`.
2. `shapes.ps1` for the shapes touched, before and after.
3. The suite with the check: clear `DEFAULT_LIB_PATH`, `GC_LIB_PATH`, `LLVM_LIB_PATH`,
`TSLANG_LIB_PATH`, `TSLANG_HOME`; set `TSLANG_VERIFY_LLVM_GLOBALS_INDEX`; `ctest -C Release -j 10
--timeout 300`. Then the suite without it.
4. Compare LLVM IR with a compiler from before the change (`--emit=llvm`, default options,
`--opt --opt_level=3`, `--mm=rc`) on the largest tests. `00param_assigned_owned.ts` differs
from run to run with any compiler (the same lines in another order) and is not a finding.

Known on the development machine: `test-borrow-facts-*` (5 tests) fail because the build cache's
`CMAKE_AR` names an MSVC toolset that is no longer installed. They pass when their commands are
rerun with the installed `lib.exe`; a CMake reconfigure fixes it.

Not done for any of this work: a Linux build, and a run of the suite with a Debug-built compiler.
The test workflows do not run on pull requests, so nothing checks Linux until one is started by
hand.
5 changes: 5 additions & 0 deletions tslang/benchmarks/compile-time/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
out/
*.exe
*.pdb
*.obj
*.ilk
54 changes: 54 additions & 0 deletions tslang/benchmarks/compile-time/profile.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Samples the call stacks of the Release compiler while it compiles one file, and prints the
# functions the time is in. Windows, no administrator rights needed.
#
# pwsh tslang/benchmarks/compile-time/profile.ps1 <source.ts> [-Flags --mm=rc] [-Interval 1]
#
# What it does:
# 1. relinks the Release tslang.exe with symbols into out/ (tslang_prof.exe + .pdb), from the link
# command MSBuild recorded for it: the build directory is not touched, and nothing is rebuilt;
# 2. builds sampler.cpp (cl, from the newest Visual Studio);
# 3. runs the compiler under the sampler and writes out/profile.txt: exclusive and inclusive
# percentages per function, and the commonest stack of the top leaves.
#
# The numbers are for locating code inside one stage, not for comparing stages: walking a deep
# stack takes longer, so the stages with deep stacks (MLIR generation, the passes) get fewer
# samples than their time. --mlir-timing is what says how long each stage takes. A per-function
# MLIR pass runs on a worker thread, which this does not sample: add -Flags --mlir-disable-threading.
param(
[Parameter(Mandatory)][string]$Source,
[string[]]$Flags = @(),
[int]$Interval = 1,
[string]$BuildDir = "$PSScriptRoot\..\..\..\__build\tslang\windows-msbuild-2026-release",
[switch]$Relink
)

$ErrorActionPreference = "Stop"
$out = Join-Path $PSScriptRoot "out"
New-Item -ItemType Directory -Force $out | Out-Null
$vs = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -latest -prerelease -products * -property installationPath
$vcvars = "$vs\VC\Auxiliary\Build\vcvars64.bat"

$exe = Join-Path $out "tslang_prof.exe"
$built = Join-Path $BuildDir "bin\tslang.exe"
if ($Relink -or -not (Test-Path $exe) -or (Get-Item $exe).LastWriteTime -lt (Get-Item $built).LastWriteTime) {
$tlog = Join-Path $BuildDir "tslang\tslang.dir\Release\tslang.tlog\link.command.1.tlog"
$cmd = ((Get-Content $tlog) | Where-Object { $_ -notmatch '^\^' }) -join ' '
$cmd = $cmd -replace '/OUT:"[^"]*"', "/OUT:`"$exe`""
$cmd = $cmd -replace '/PDB:"[^"]*"', "/PDB:`"$out\tslang_prof.pdb`""
$cmd = $cmd -replace '/IMPLIB:"[^"]*"', "/IMPLIB:`"$out\tslang_prof.lib`""
$cmd = $cmd -replace '/ERRORREPORT:\S+', ''
$cmd += ' /DEBUG:FULL /OPT:REF /OPT:NOICF'
Set-Content "$out\link.rsp" $cmd -Encoding Unicode
Push-Location (Join-Path $BuildDir "tslang")
try { cmd /c "`"$vcvars`" >nul && link @`"$out\link.rsp`"" 2>&1 | Select-Object -Last 3 } finally { Pop-Location }
}

$sampler = Join-Path $out "sampler.exe"
if (-not (Test-Path $sampler)) {
Push-Location $out
try { cmd /c "`"$vcvars`" >nul && cl /nologo /std:c++17 /O2 /EHsc `"$PSScriptRoot\sampler.cpp`" /Fe:sampler.exe dbghelp.lib" 2>&1 | Select-Object -Last 3 } finally { Pop-Location }
}

& $sampler $Interval $exe --emit=obj --no-default-lib @Flags $Source -o "$out\profiled.obj" > "$out\profile.txt" 2>&1
"written $out\profile.txt"
Get-Content "$out\profile.txt" -TotalCount 60
126 changes: 126 additions & 0 deletions tslang/benchmarks/compile-time/sampler.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
// Stack sampler: runs a command, samples its main thread's call stack, prints exclusive and
// inclusive function counts. Usage: sampler.exe <interval_ms> <command line...>
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
#include <dbghelp.h>
#include <algorithm>
#include <cstdio>
#include <map>
#include <set>
#include <string>
#include <vector>

static std::string symName(HANDLE proc, DWORD64 addr)
{
char buf[sizeof(SYMBOL_INFO) + 1024];
auto *sym = (SYMBOL_INFO *)buf;
sym->SizeOfStruct = sizeof(SYMBOL_INFO);
sym->MaxNameLen = 1000;
DWORD64 disp = 0;
if (SymFromAddr(proc, addr, &disp, sym))
{
std::string s(sym->Name);
if (s.size() > 170) s = s.substr(0, 170) + "...";
return s;
}
char tmp[64];
sprintf(tmp, "0x%llx", (unsigned long long)addr);
return tmp;
}

int main(int argc, char **argv)
{
if (argc < 3) return 2;
int interval = atoi(argv[1]);
std::string cmd;
for (int i = 2; i < argc; i++)
{
if (i > 2) cmd += " ";
cmd += std::string("\"") + argv[i] + "\"";
}

STARTUPINFOA si{sizeof(si)};
PROCESS_INFORMATION pi{};
HANDLE nul = CreateFileA("NUL", GENERIC_WRITE, FILE_SHARE_WRITE, nullptr, OPEN_EXISTING, 0, nullptr);
SetHandleInformation(nul, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT);
si.dwFlags = STARTF_USESTDHANDLES;
si.hStdOutput = nul;
si.hStdError = nul;
if (!CreateProcessA(nullptr, cmd.data(), nullptr, nullptr, TRUE, CREATE_SUSPENDED, nullptr, nullptr, &si, &pi))
{
printf("CreateProcess failed %lu\n", GetLastError());
return 1;
}
SymSetOptions(SYMOPT_UNDNAME | SYMOPT_DEFERRED_LOADS | SYMOPT_LOAD_LINES);
ResumeThread(pi.hThread);
Sleep(150);
SymInitialize(pi.hProcess, nullptr, TRUE);

std::vector<std::vector<DWORD64>> stacks;
while (WaitForSingleObject(pi.hProcess, interval) == WAIT_TIMEOUT)
{
if (SuspendThread(pi.hThread) == (DWORD)-1) break;
CONTEXT ctx{};
ctx.ContextFlags = CONTEXT_FULL;
std::vector<DWORD64> st;
if (GetThreadContext(pi.hThread, &ctx))
{
STACKFRAME64 f{};
f.AddrPC.Offset = ctx.Rip; f.AddrPC.Mode = AddrModeFlat;
f.AddrFrame.Offset = ctx.Rbp; f.AddrFrame.Mode = AddrModeFlat;
f.AddrStack.Offset = ctx.Rsp; f.AddrStack.Mode = AddrModeFlat;
for (int i = 0; i < 96; i++)
{
if (!StackWalk64(IMAGE_FILE_MACHINE_AMD64, pi.hProcess, pi.hThread, &f, &ctx, nullptr,
SymFunctionTableAccess64, SymGetModuleBase64, nullptr))
break;
if (!f.AddrPC.Offset) break;
st.push_back(f.AddrPC.Offset);
}
}
ResumeThread(pi.hThread);
if (!st.empty()) stacks.push_back(std::move(st));
}

std::map<DWORD64, std::string> names;
auto name = [&](DWORD64 a) -> const std::string & {
auto it = names.find(a);
if (it == names.end()) it = names.emplace(a, symName(pi.hProcess, a)).first;
return it->second;
};
std::map<std::string, int> excl, incl;
std::map<std::string, std::map<std::string, int>> leafStacks;
for (auto &st : stacks)
{
excl[name(st[0])]++;
std::set<std::string> seen;
for (auto a : st) seen.insert(name(a));
for (auto &s : seen) incl[s]++;
std::string key;
for (size_t i = 1; i < st.size() && i < 14; i++) key += " <- " + name(st[i]) + "\n";
leafStacks[name(st[0])][key]++;
}
auto top = [&](std::map<std::string, int> &m, int n, const char *title) {
std::vector<std::pair<int, std::string>> v;
for (auto &kv : m) v.push_back({kv.second, kv.first});
std::sort(v.rbegin(), v.rend());
printf("\n== %s (%zu samples) ==\n", title, stacks.size());
for (int i = 0; i < n && i < (int)v.size(); i++)
printf("%6.1f%% %s\n", 100.0 * v[i].first / stacks.size(), v[i].second.c_str());
return v;
};
auto ex = top(excl, 30, "exclusive");
top(incl, 70, "inclusive");
printf("\n== most common stack of the top 6 leaves ==\n");
for (int i = 0; i < 6 && i < (int)ex.size(); i++)
{
auto &m = leafStacks[ex[i].second];
auto best = std::max_element(m.begin(), m.end(), [](auto &a, auto &b) { return a.second < b.second; });
printf("%s (%d of %d samples with this stack)\n%s\n", ex[i].second.c_str(), best->second, ex[i].first, best->first.c_str());
}
DWORD code = 0;
GetExitCodeProcess(pi.hProcess, &code);
printf("exit code %lu\n", code);
SymCleanup(pi.hProcess);
return 0;
}
Loading
Loading