mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
perf(compression/code): avoid a UTF-8 copy per code block in byte-to-char mapping (#3169)
## Description
`CodeStructureHandler._byte_spans_to_char_spans` converts tree-sitter's
byte offsets to character offsets for each compressed code block. Its
ASCII fast path was:
```python
n_bytes = len(content.encode("utf-8"))
if n_bytes == len(content):
return spans
```
`content.encode("utf-8")` allocates a full UTF-8 byte copy of the whole
code block, which is then discarded — just to compare its length against
`len(content)`. For the common case (ASCII source, byte == char),
`content.isascii()` answers the same question in C with no allocation.
The non-ASCII branch additionally re-encoded **every character** in the
loop (`len(ch.encode("utf-8"))`) to get its UTF-8 width — one small
allocation per character. A character's width (1-4 bytes) is fully
determined by its code point, so it can be derived with `ord(ch)` and no
encoding.
This runs per code block on the compression path, so for code-heavy
traffic the discarded per-block allocation adds up. Output is
byte-for-byte identical.
Benchmark (`_byte_spans_to_char_spans` on a ~20 KB ASCII block, mean of
20000 calls):
```
old (len(encode) == len) : 0.45 us/call (+ a 20 KB bytes allocation)
new (isascii()) : 0.06 us/call (~7x faster, no allocation)
```
Correctness was verified by comparing the old and new implementations on
mixed content (`café 🚀 语言` — 2/4/3-byte characters): the remapped span
offsets are identical.
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [x] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- `headroom/compression/handlers/code_handler.py`
(`_byte_spans_to_char_spans`): use `content.isascii()` for the fast-path
check (no UTF-8 allocation), and derive each character's UTF-8 width
from its code point instead of re-encoding it per character.
- `tests/test_compression/test_code_handler.py`: added
`TestByteSpanToCharSpan` — ASCII spans returned unchanged, and non-ASCII
byte offsets (café / rocket / CJK) remapped to the correct character
offsets including the exclusive-end boundary.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
### Test Output
```text
tests/test_compression/test_code_handler.py -> 24 passed, 8 skipped (tree-sitter not installed)
uvx ruff@0.16.2 check headroom/compression/handlers/code_handler.py tests/test_compression/test_code_handler.py -> All checks passed!
uvx mypy@1.20.2 headroom/compression/handlers/code_handler.py -> Success: no issues found in 1 source file
```
## Real Behavior Proof
- Environment: Windows 11, Python 3.12.11, project venv, pytest 9.1.1,
ruff 0.16.2 and mypy 1.20.2 via uvx.
- Exact command / steps: ran the old and new implementations side by
side on ASCII and on mixed non-ASCII content (`café 🚀 语言`) and confirmed
identical remapped span offsets; benchmarked the ASCII path (0.45us ->
0.06us, ~7x, and the new path allocates nothing). Added the regression
test and ran the file.
- Observed result: identical span mapping; the per-block UTF-8
allocation on the ASCII fast path is gone, and the non-ASCII loop no
longer allocates per character.
- Not tested: an end-to-end code-compression request through
`UniversalCompressor`; the static helper is exercised directly with
byte-offset spans, which is exactly what tree-sitter feeds it.
## Runtime Rollout Safety
- Rollout-managed feature(s): none. This is an internal offset-mapping
helper in the code structure handler, not a rollout-channel-gated
runtime feature.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: no. The returned spans are identical
for ASCII and non-ASCII content; only the work done to compute them is
cheaper.
- Kill switch / disable path: N/A.
- Unsafe override required: no.
- Qualification impact: less per-block allocation/CPU when mapping code
spans; identical output.
- Rollback path: revert this PR; the helper returns to encoding the
content for the length check and per-character.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation (N/A:
internal helper, output unchanged)
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`
## Additional Notes
Scope is deliberately small and behavior-preserving: `content.isascii()`
is exactly equivalent to "every UTF-8 byte is one character," and the
code-point width table (`<0x80 -> 1`, `<0x800 -> 2`, `<0x10000 -> 3`,
else `4`) matches Python's UTF-8 encoding for every `str` character.
This commit is contained in:
@@ -605,16 +605,24 @@ class CodeStructureHandler(BaseStructureHandler):
|
||||
returned unchanged. Otherwise a byte->char table is built once
|
||||
and every span endpoint is remapped.
|
||||
"""
|
||||
n_bytes = len(content.encode("utf-8"))
|
||||
if n_bytes == len(content):
|
||||
# ASCII fast path: every byte is one character, so tree-sitter's byte
|
||||
# offsets are already character offsets. ``content.isascii()`` checks
|
||||
# this in C without allocating, where ``len(content.encode("utf-8"))``
|
||||
# built (and discarded) a full UTF-8 copy of the content on every code
|
||||
# block just to compare lengths.
|
||||
if content.isascii():
|
||||
return spans
|
||||
|
||||
# byte_to_char[b] = index of the character containing byte b;
|
||||
# byte_to_char[n_bytes] = len(content) so exclusive ends map.
|
||||
# byte_to_char[n_bytes] = len(content) so exclusive ends map. A
|
||||
# character's UTF-8 width is derived from its code point (1-4 bytes)
|
||||
# rather than re-encoding every character individually in the loop.
|
||||
n_bytes = len(content.encode("utf-8"))
|
||||
byte_to_char = [0] * (n_bytes + 1)
|
||||
byte_pos = 0
|
||||
for char_idx, ch in enumerate(content):
|
||||
ch_width = len(ch.encode("utf-8"))
|
||||
cp = ord(ch)
|
||||
ch_width = 1 if cp < 0x80 else 2 if cp < 0x800 else 3 if cp < 0x10000 else 4
|
||||
for b in range(byte_pos, byte_pos + ch_width):
|
||||
byte_to_char[b] = char_idx
|
||||
byte_pos += ch_width
|
||||
|
||||
@@ -353,3 +353,40 @@ class TestTreeSitterContainers:
|
||||
f"class code preserved {result.preservation_ratio:.0%} — "
|
||||
"container bodies are leaking into the structural mask"
|
||||
)
|
||||
|
||||
|
||||
class TestByteSpanToCharSpan:
|
||||
"""_byte_spans_to_char_spans must map tree-sitter byte offsets to character
|
||||
offsets. The ASCII fast path returns spans unchanged (byte == char) without
|
||||
allocating a UTF-8 copy; the non-ASCII path derives each character's width
|
||||
from its code point instead of re-encoding it."""
|
||||
|
||||
def test_ascii_returns_spans_unchanged(self):
|
||||
from headroom.compression.handlers.code_handler import CodeSpan
|
||||
|
||||
spans = [
|
||||
CodeSpan(start=0, end=5, role="sig", is_structural=True),
|
||||
CodeSpan(start=6, end=11, role="body", is_structural=False),
|
||||
]
|
||||
out = CodeStructureHandler._byte_spans_to_char_spans(spans, "def f():\n pass\n")
|
||||
assert [(s.start, s.end) for s in out] == [(0, 5), (6, 11)]
|
||||
|
||||
def test_non_ascii_remaps_byte_offsets_to_char_offsets(self):
|
||||
from headroom.compression.handlers.code_handler import CodeSpan
|
||||
|
||||
# café (é = 2 bytes), 🚀 (4 bytes), 语言 (3 bytes each).
|
||||
content = "x = 'café 🚀 语言'\n"
|
||||
enc = content.encode("utf-8")
|
||||
# A structural span covering the whole line, plus one covering 'return'-like
|
||||
# region: give byte offsets and expect character offsets back.
|
||||
whole = CodeSpan(start=0, end=len(enc), role="body", is_structural=True)
|
||||
# byte offset of the closing quote vs its character offset
|
||||
quote_byte = enc.rindex(b"'")
|
||||
quote_char = content.rindex("'")
|
||||
marker = CodeSpan(start=quote_byte, end=len(enc), role="sig", is_structural=True)
|
||||
|
||||
out = CodeStructureHandler._byte_spans_to_char_spans([whole, marker], content)
|
||||
assert out[0].start == 0
|
||||
assert out[0].end == len(content) # exclusive end maps to char length
|
||||
assert out[1].start == quote_char # byte offset correctly remapped
|
||||
assert out[1].end == len(content)
|
||||
|
||||
Reference in New Issue
Block a user