Repository navigation
docs(tl_kernels): the caller that pads these kernels is laya.fast, not base.pad_batch - #1148
Conversation
…t base.pad_batch pad_batch has one production call site (laya/backends/compile.py:111, the compile route); laya/fast.py is the only module that imports tl_kernels, and FastLaya._forward_unlocked does its own bucketing -- bucket_rows for rows, an inlined copy of bucket_tokens' arithmetic against FastLaya.DYNAMIC_MAX_L/LONG_BUCKET for tokens. Retune pad_batch for TileLang and nothing on the TileLang route changes, so name the real caller and gate the call graph, the inlining and the duplicated constants off the AST (no tilelang import, so this runs CPU-only).
…ccept a direct bucket_rows call
|
Merged. The attribution was false in a way nothing could catch, and the AST checks are the right way to keep it true. Confirmed both sets: The second check is the better one. Pinning the ban as a regex against the docstring is slightly unusual and justified here: it catches the specific wrong sentence coming back, and the error text explains the call graph rather than just failing. |
What
laya/tl_kernels.py's module docstring told the reader that the caller of these kernels islaya.backends.base.pad_batch:It is not.
pad_batchhas exactly one production call site,laya/backends/compile.py:111-- the AOTInductorroute -- and
laya/fast.py:10is the only module in the package that importstl_kernels. The two sets aredisjoint: the padding these kernels actually see happens in
laya/fast.py:214-219,FastLaya._forward_unlocked, which takes its row bucket frombucket_rows(through_bucket_n, imported atlaya/fast.py:11) but inlines the token bucketing against its own class attributes (laya/fast.py:115-116)instead of calling
bucket_tokens. The docstring now names that caller, says which half is shared and whichis duplicated, and keeps
pad_batchin the sentence as the compile route's copy. 6 insertions and 3 deletions.Why
The wrong name has a working consequence.
bucket_rowsis shared, but the token policy exists twice --laya/backends/base.py:21-22andlaya/fast.py:115-116, bothDYNAMIC_MAX_L = 256,LONG_BUCKET = 64. Amaintainer who retunes TileLang sequence padding by editing
pad_batch,bucket_tokens, orbase.DYNAMIC_MAX_Lchanges nothing on the TileLang route, and nothing in the tree notices:
tests/test_confidence.py's existingtl-kernels gate checks the docstring's wording ("power of two", "16-token bucket",
bucket_rows,bucket_tokens) and the row bucketing, never who calls what. The duplicated constants are also why thedocstring could be wrong for so long while still describing the right numbers -- it does describe the same
policy on both routes, it just attributes it to a function on the other one.
No behaviour changes here, and none was claimed:
tilelangis not installed on this machine and the fast pathneeds CUDA, so every check below is AST- or arithmetic-level and runs CPU-only.
How it was verified
Call graph read out of the AST, no
tilelangimport (/tmp/probe_tl_caller.py):The
all equal: Trueline isbase.bucket_tokens(L0, 1024)compared against the inlined expression forL0in(1, 3, 16, 17, 255, 256, 257, 300, 1000, 1025)-- every row printed as(L0, inline, base, equal)and all ten matched, so the docstring is describing one policy that happens to live in two places, which is
what makes the duplication worth a tripwire rather than a correction.
Three tests in
tests/test_confidence.py, added to the script runner alongside the existing tl-kernels gates:test_tl_kernels_names_a_caller_that_is_on_the_kernels_route-- derives the importer set and the caller setfrom
laya/**by AST and requires them to be exactly{laya/fast.py}and{laya/backends/compile.py}anddisjoint; then bans the "caller … pad_batch" phrasing and requires the docstring to name
laya.fastand_forward_unlocked. The two set equalities fail with a message that tells the reader to re-derive ratherthan to edit the test.
test_the_fast_path_still_inlines_the_token_bucket_the_docstring_says_it_repeats--ast.unparses_forward_unlockedand requiresself.DYNAMIC_MAX_L/self.LONG_BUCKETto be used there,bucket_tokens(to be absent, and the row pad to come from
bucket_rows(through_bucket_nor directly).test_the_two_bucket_policies_the_docstring_describes_are_still_the_same_numbers-- readsFastLaya.DYNAMIC_MAX_L/LONG_BUCKETas class literals (no import, because this machine cannot importlaya.fast) and requires them to equallaya.backends.base's, then requires the docstring to print thebucket numbers the code uses (
16-token bucket, and%d-token bucketfromLONG_BUCKET).Seven mutants, each applied to the committed tree and reverted before the next (
git checkout --per file):TileLangBackendas the callerrc=1 KILLED--222 passed, 1 failedlaya.backends.base.pad_batch"rc=1 KILLED64->128rc=1 KILLEDFastLaya.DYNAMIC_MAX_L = 512, docstring untouchedrc=1 KILLED_forward_unlockeddrops the class constants (g = 16)rc=1 KILLEDlaya/fast.pygains apad_batchcallrc=1 KILLEDcompile.pystops callingpad_batchrc=1 KILLEDThe last two are the ones that make the first test more than a string match: a future PR that puts
pad_batchback on the kernels' route fails here instead of silently making the docstring true again by accident.
Gates, in this worktree:
tests/test_confidence.pyis a script suite:pytestcollects nothing from it (SystemExit: 0at import, thesame on
upstream/main), so the 220 -> 223 count comes from running it directly.ruff check tests/is outsidethe CI lint path and was not run.
Diff scan for secrets: the broad pattern (
api[_-]?key|secret|token|password|bearer|sk-…|ghp_|AKIA|hf_…) gives17 hits, and every one is the word
tokeninsidebucket_tokens,token bucketortoken dim. Thecredential-shaped pattern (
(api_key|secret|password|bearer|ghp_|AKIA|hf_)[A-Za-z0-9_-]* [:=] <value>) gives0 hits. No value, no key material.
Deconfliction:
laya/tl_kernels.py,laya/backends/base.pyandlaya/backends/compile.pyare touched by noopen PR.
tests/test_confidence.pyis touched only by #1119, whose single hunk in that file is@@ -281,6 +281,26 @@; this change's hunk there is@@ -2041,9 +2041,149 @@, so no shared line. The threefiles the gate reads but does not edit are
laya/fast.py,laya/backends/base.pyandlaya/backends/compile.py; of those only #921 toucheslaya/fast.py, and its one hunk there is@@ -30,6 +30,8 @@(theFastLaya.__init__signature area, well clear of the constants at:115-116and thepadding at
:214-219) --gh pr diff 921matches none ofDYNAMIC_MAX_L,LONG_BUCKET,bucket_rows,bucket_tokens,_bucket_norpad_batch.Branch has two commits:
bb973e02(the docstring and the gate) andc3b0d312(one wording tightening, plusletting the row check accept a direct
bucket_rowscall as well as_bucket_n, so a faithful refactor is notpunished for naming the helper it inlined).
Checklist
main