feat(ir): add on-disk compile cache for kernels and implement caching… by zhenrongliew · Pull Request #769 · QuEraComputing/kirin

zhenrongliew · 2026-10-05T16:35:14Z

Add an opt-in on-disk cache for compiled kernels

Kernel decorators compile when a module is imported: they lower the function and
run the dialect group's passes, again in every new process, even when nothing
changed. With KIRIN_COMPILE_CACHE_DIR set, each compiled kernel is now saved,
and a later process loads it instead of running the passes, as long as nothing it
depends on has changed. Without the variable, behaviour is unchanged.

Key. A SHA-256 over the lowered IR (which holds the values of the globals the
function reads), the keys of the kernels it calls, the dialect names and
run_pass source, the decorator options, the function's file and line, and the
Python and package versions. Any change gives a new key, so a stale entry is
never found.

Storage. The compiled code is pickled. The kernel itself, its callees and its
dialect group are saved as references and relinked to the live objects on load;
singleton types are rebuilt as the same objects. Files are written atomically.

Limitations

Loading a pickle can run code: only point the cache at a directory you trust.
Editing an editable install doesn't change its version: clear the cache after
changing library code.
Loaded kernels hold copies of the constants they captured.

Testing

test/ir/test_compile_cache.py: four runs in fresh processes (empty cache,
nothing changed, callee changed, global changed) check which kernels recompile
and their results.
Full suite passes with the cache off, cold and warm.
40 kernels, each calling the previous one: import takes 0.28 s without the
cache and 0.03 s with a warm cache.

🤖 Generated with Claude Code

… logic

github-actions · 2026-10-05T16:36:11Z

☂️ Code Coverage

current status: ✅

Overall Coverage

Statements	Covered	Coverage	Threshold	Status
12307	11133	90%	0%	🟢

New Files

File	Coverage	Status
src/kirin/ir/compile_cache.py	94%	🟢
TOTAL	94%	🟢

Modified Files

File	Coverage	Status
src/kirin/ir/group.py	92%	🟢
TOTAL	92%	🟢

updated for commit: 34d65a0 by action🐍

github-actions · 2026-10-05T16:36:14Z

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-08 01:59 UTC

codecov · 2026-10-05T16:36:22Z

Codecov Report

❌ Patch coverage is 94.58333% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/kirin/ir/compile_cache.py	94.24%	13 Missing ⚠️

📢 Thoughts on this report? Let us know!

…efault behavior

…enhance test coverage

kaihsin · 2026-10-06T17:35:57Z

+    if code.source is not None and code.source.lineno_begin != mt.lineno_begin:
+        file, saved = code.source.file, code.source.lineno_begin
+        for stmt in code.walk():
+            source = stmt.source
+            if source and source.file == file and source.lineno_begin == saved:
+                source.lineno_begin = mt.lineno_begin


I think this work now, but I think we should really redesign the ir.Method and how SourceInfo is. this seems like crazy we need to re-walk the whole IR just to update the lineno offset @Roger-luo @zhenrongliew.

Ideally source info is stored in an areana and we only point certain IR node to the arena ID, so you can shift the lineno by iterating a piece of continuous memory without walking the IR. But this is not super beneficial in Python's object model because you don't really have a continuous memory anyways.

Roger-luo · 2026-10-07T09:46:29Z

can we improve the coverage a bit to get this PR in? @copilot

Co-authored-by: Roger-luo <8445510+Roger-luo@users.noreply.github.com>

Copilot · 2026-10-07T09:50:05Z

can we improve the coverage a bit to get this PR in? @copilot

Added direct tests for cache directory selection and fingerprinting; compile_cache.py coverage is now 50% in the targeted run. Commit: __SHORT_HASH__.

github-actions · 2026-10-08T01:59:03Z

Backport results for `a6481d6`

Succeeded:

release-0-22: Backport PR #769 to release-0-22 #773

Automated backport of PR #769 (a6481d6) to `release-0-22`. Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

feat(ir): add on-disk compile cache for kernels and implement caching…

06c6e8e

… logic

zhenrongliew requested review from Roger-luo, kaihsin and neelay893 October 5, 2026 16:35

kaihsin reviewed Oct 5, 2026

View reviewed changes

Comment thread src/kirin/ir/group.py

Comment thread src/kirin/ir/group.py

zhenrongliew added 3 commits October 5, 2026 17:03

feat(ir): enhance on-disk compile cache with directory override and d…

2a1c431

…efault behavior

feat(ir): update compile cache logic to handle kernel relocation and …

b65a152

…enhance test coverage

feat(ir): add test for kernel relocation error handling in compile cache

90dce6f

kaihsin reviewed Oct 6, 2026

View reviewed changes

Copilot started work on behalf of Roger-luo October 7, 2026 09:46 View session

test(ir): expand compile cache coverage

8ec15ee

Co-authored-by: Roger-luo <8445510+Roger-luo@users.noreply.github.com>

Copilot finished work on behalf of Roger-luo October 7, 2026 09:50

fix isort and added coverage test

34d65a0

kaihsin approved these changes Oct 7, 2026

View reviewed changes

zhenrongliew added the backport 0.22 label Oct 8, 2026

zhenrongliew merged commit a6481d6 into main Oct 8, 2026
11 checks passed

zhenrongliew deleted the dl/kernel-compile-cache branch October 8, 2026 01:58

github-actions Bot mentioned this pull request Oct 8, 2026

Backport PR #769 to release-0-22 #773

Merged

zhenrongliew pushed a commit that referenced this pull request Oct 8, 2026

Backport PR #769 to release-0-22 (#773)

c9bb306

Automated backport of PR #769 (a6481d6) to `release-0-22`. Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

This was referenced Oct 9, 2026

fix(lowering): order if/else phi and yield names by first definition #777

Open

if/else lowering orders phi arguments by string hash, so the IR changes with PYTHONHASHSEED #775

Open

Navigation Menu

Repository navigation

feat(ir): add on-disk compile cache for kernels and implement caching… - #769

feat(ir): add on-disk compile cache for kernels and implement caching…#769
zhenrongliew merged 6 commits into
mainfrom
dl/kernel-compile-cache

zhenrongliew commented Oct 5, 2026

Uh oh!

github-actions Bot commented Oct 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 5, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Oct 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

kaihsin Oct 6, 2026

Uh oh!

Roger-luo Oct 7, 2026

Uh oh!

Roger-luo commented Oct 7, 2026

Uh oh!

Copilot AI commented Oct 7, 2026

Uh oh!

Uh oh!

github-actions Bot commented Oct 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

zhenrongliew commented Oct 5, 2026

Add an opt-in on-disk cache for compiled kernels

Uh oh!

github-actions Bot commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

☂️ Code Coverage

Overall Coverage

New Files

Modified Files

Uh oh!

github-actions Bot commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

kaihsin Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

Roger-luo Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

Roger-luo commented Oct 7, 2026

Uh oh!

Copilot AI commented Oct 7, 2026

Uh oh!

Uh oh!

github-actions Bot commented Oct 8, 2026

Backport results for a6481d6

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented Oct 5, 2026 •

edited

Loading

github-actions Bot commented Oct 5, 2026 •

edited

Loading

codecov Bot commented Oct 5, 2026 •

edited

Loading

Backport results for `a6481d6`