Skip to content

perf(python): pass the module to pyfunctions to keep CPython 3.14 call specialization - #58

Merged
mrecachinas merged 1 commit into
ci/stacked-pr-checksfrom
perf/pyo3-pass-module
Sep 23, 2026
Merged

mrecachinas merged 1 commit into
ci/stacked-pr-checksfrom
perf/pyo3-pass-module

Conversation

@mrecachinas

@mrecachinas mrecachinas commented Sep 23, 2026 •

Copy link
Copy Markdown
Owner

Finding: PyO3 0.29 gives every #[pyfunction] without pass_module the flag METH_STATIC (ml_flags = 0xa2). CPython 3.14's CALL_BUILTIN_FAST_WITH_KEYWORDS specialization rejects that flag, so every call to a module function deoptimizes to the generic PyObject_Vectorcall path.

Fix: all 17 module functions now take pass_module (ml_flags = 0x82), which keeps the specialized call path. A regression test checks that each function's __self__ is the extension module; the test fails without this change.

Interleaved A/B in one process (Apple M4 Max, CPython 3.14, ns/call):

Call Before After Speedup
hamming_distance_string 16 chars 31.9 28.9 1.11×
hamming_distance_bytes 16 B 29.1 26.4 1.10×
set_algo 36.8 31.5 1.17×

The saving is about 3 ns per call on every function.

@mrecachinas
mrecachinas added this pull request to stack #60 September 23, 2026 01:29
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown

📊 Benchmark Comparison Results

Status Benchmark Base PR Delta
⚠️ check_bytes_arrays_best_within_dist[16384 elems,s=64,at 0] 0.0551ms 0.0686ms 24.6% slower
⚠️ check_bytes_arrays_best_within_dist[16384 elems,s=64,end] 0.0552ms 0.0686ms 24.3% slower
⚠️ check_bytes_arrays_all_within_dist[16384 elems,s=64,end] 0.0499ms 0.0551ms 10.3% slower
✅ fixed_width_array_scan_matrix[all-threshold_d_minus_1-16] 0.0073ms 0.0008ms 89.3% faster
✅ fixed_width_array_scan_matrix[all-random_no_match-16] 0.0073ms 0.0008ms 89.3% faster
✅ fixed_width_array_scan_matrix[all-exact_early-16] 0.0074ms 0.0008ms 88.7% faster
✅ fixed_width_array_scan_matrix[all-exact_late-16] 0.0074ms 0.0009ms 88.5% faster
✅ fixed_width_array_scan_matrix[all-threshold_d-16] 0.0074ms 0.0009ms 88.3% faster
✅ fixed_width_array_scan_matrix[all-threshold_d_plus_1-16] 0.0074ms 0.0009ms 88.3% faster
✅ fixed_width_array_scan_matrix[all-exact_mid-16] 0.0074ms 0.0009ms 88.3% faster
✅ check_bytes_arrays_all_within_dist[ 512 elems,s=16,mid] 0.0038ms 0.0005ms 87.0% faster
✅ check_bytes_arrays_all_within_dist[ 512 elems,s=16,end] 0.0038ms 0.0005ms 86.8% faster
✅ check_bytes_arrays_all_within_dist[ 512 elems,s=16,at 0] 0.0038ms 0.0006ms 85.0% faster
✅ fixed_width_array_scan_matrix[all-threshold_d_minus_1-32] 0.0050ms 0.0016ms 68.9% faster
✅ fixed_width_array_scan_matrix[all-random_no_match-32] 0.0050ms 0.0016ms 68.9% faster
✅ fixed_width_array_scan_matrix[all-exact_early-32] 0.0051ms 0.0016ms 68.1% faster
✅ fixed_width_array_scan_matrix[all-exact_late-32] 0.0051ms 0.0016ms 67.9% faster
✅ fixed_width_array_scan_matrix[all-threshold_d_plus_1-32] 0.0051ms 0.0016ms 67.5% faster
✅ fixed_width_array_scan_matrix[all-exact_mid-32] 0.0051ms 0.0016ms 67.5% faster
✅ fixed_width_array_scan_matrix[all-threshold_d-32] 0.0051ms 0.0016ms 67.5% faster
✅ check_bytes_arrays_all_within_dist[ 1024 elems,s=32,mid] 0.0051ms 0.0017ms 66.7% faster
✅ check_bytes_arrays_all_within_dist[ 1024 elems,s=32,at 0] 0.0050ms 0.0017ms 66.4% faster
✅ check_bytes_arrays_all_within_dist[ 1024 elems,s=32,end] 0.0051ms 0.0017ms 66.3% faster
➖ 81 benchmarks within noise (click to expand)
Benchmark Base PR Delta
check_bytes_arrays_all_within_dist[16384 elems,s=64,at 0] 0.0502ms 0.0550ms 9.7% slower
check_bytes_arrays_all_within_dist[16384 elems,s=64,mid] 0.0502ms 0.0551ms 9.7% slower
check_bytes_arrays_best_within_dist[ 512 elems,s=16,at 0] 0.0001ms 0.0001ms 0.6% faster
check_bytes_arrays_best_within_dist[ 512 elems,s=16,end] 0.0004ms 0.0004ms 0.7% faster
check_bytes_arrays_best_within_dist[ 512 elems,s=16,mid] 0.0002ms 0.0002ms 0.9% faster
check_bytes_arrays_best_within_dist[ 1024 elems,s=32,at 0] 0.0017ms 0.0017ms 0.2% slower
check_bytes_arrays_best_within_dist[ 1024 elems,s=32,end] 0.0017ms 0.0017ms 0.4% slower
check_bytes_arrays_best_within_dist[ 1024 elems,s=32,mid] 0.0016ms 0.0017ms 0.8% slower
check_bytes_arrays_best_within_dist[16384 elems,s=64,mid] 0.0557ms 0.0596ms 6.9% slower
check_bytes_arrays_first_within_dist[ 512 elems,s=16,at 0] 0.0001ms 0.0001ms 0.5% faster
check_bytes_arrays_first_within_dist[ 512 elems,s=16,end] 0.0004ms 0.0004ms 2.4% slower
check_bytes_arrays_first_within_dist[ 512 elems,s=16,mid] 0.0002ms 0.0002ms 0.0% faster
check_bytes_arrays_first_within_dist[ 1024 elems,s=32,at 0] 0.0001ms 0.0001ms 0.7% slower
check_bytes_arrays_first_within_dist[ 1024 elems,s=32,end] 0.0015ms 0.0015ms 0.6% slower
check_bytes_arrays_first_within_dist[ 1024 elems,s=32,mid] 0.0007ms 0.0007ms 0.1% faster
check_bytes_arrays_first_within_dist[16384 elems,s=64,at 0] 0.0001ms 0.0001ms 0.3% faster
check_bytes_arrays_first_within_dist[16384 elems,s=64,end] 0.0503ms 0.0550ms 9.3% slower
check_bytes_arrays_first_within_dist[16384 elems,s=64,mid] 0.0253ms 0.0276ms 9.2% slower
check_bytes_within_dist[127 bytes,d=500] 0.0001ms 0.0001ms 2.1% slower
check_bytes_within_dist[16 bytes,d=0] 0.0001ms 0.0001ms 1.4% slower
check_bytes_within_dist[64 bytes,d=100] 0.0001ms 0.0001ms 2.6% slower
hex_within_dist 0.0001ms 0.0001ms 1.9% faster
fixed_width_array_scan_matrix[best-exact_early-16] 0.0001ms 0.0001ms 0.1% slower
fixed_width_array_scan_matrix[best-exact_early-32] 0.0001ms 0.0001ms 0.1% faster
fixed_width_array_scan_matrix[best-exact_late-16] 0.0007ms 0.0007ms 0.5% faster
fixed_width_array_scan_matrix[best-exact_late-32] 0.0016ms 0.0016ms 2.6% slower
fixed_width_array_scan_matrix[best-exact_mid-16] 0.0004ms 0.0004ms 0.1% faster
fixed_width_array_scan_matrix[best-exact_mid-32] 0.0008ms 0.0008ms 2.4% slower
fixed_width_array_scan_matrix[best-random_no_match-16] 0.0007ms 0.0007ms 0.3% faster
fixed_width_array_scan_matrix[best-random_no_match-32] 0.0015ms 0.0016ms 2.7% slower
fixed_width_array_scan_matrix[best-threshold_d-16] 0.0008ms 0.0007ms 1.1% faster
fixed_width_array_scan_matrix[best-threshold_d-32] 0.0016ms 0.0016ms 2.4% slower
fixed_width_array_scan_matrix[best-threshold_d_minus_1-16] 0.0007ms 0.0007ms 0.3% faster
fixed_width_array_scan_matrix[best-threshold_d_minus_1-32] 0.0015ms 0.0016ms 2.7% slower
fixed_width_array_scan_matrix[best-threshold_d_plus_1-16] 0.0008ms 0.0007ms 1.2% faster
fixed_width_array_scan_matrix[best-threshold_d_plus_1-32] 0.0016ms 0.0016ms 2.4% slower
fixed_width_array_scan_matrix[first-exact_early-16] 0.0001ms 0.0001ms 2.1% slower
fixed_width_array_scan_matrix[first-exact_early-32] 0.0001ms 0.0001ms 0.4% faster
fixed_width_array_scan_matrix[first-exact_late-16] 0.0007ms 0.0007ms 0.1% slower
fixed_width_array_scan_matrix[first-exact_late-32] 0.0014ms 0.0014ms 0.2% slower
fixed_width_array_scan_matrix[first-exact_mid-16] 0.0004ms 0.0004ms 0.8% slower
fixed_width_array_scan_matrix[first-exact_mid-32] 0.0007ms 0.0007ms 0.1% slower
fixed_width_array_scan_matrix[first-random_no_match-16] 0.0007ms 0.0007ms 2.3% faster
fixed_width_array_scan_matrix[first-random_no_match-32] 0.0014ms 0.0014ms 0.1% slower
fixed_width_array_scan_matrix[first-threshold_d-16] 0.0004ms 0.0004ms 0.4% faster
fixed_width_array_scan_matrix[first-threshold_d-32] 0.0007ms 0.0007ms 0.8% slower
fixed_width_array_scan_matrix[first-threshold_d_minus_1-16] 0.0007ms 0.0007ms 0.1% slower
fixed_width_array_scan_matrix[first-threshold_d_minus_1-32] 0.0015ms 0.0014ms 3.8% faster
fixed_width_array_scan_matrix[first-threshold_d_plus_1-16] 0.0005ms 0.0004ms 16.8% faster
fixed_width_array_scan_matrix[first-threshold_d_plus_1-32] 0.0007ms 0.0007ms 0.1% slower
hd_bytes[1000-diff] 0.0001ms 0.0001ms 1.9% faster
hd_bytes[1000-same] 0.0001ms 0.0001ms 1.3% faster
hd_bytes[1024-diff] 0.0001ms 0.0001ms 2.8% faster
hd_bytes[1024-same] 0.0001ms 0.0001ms 1.7% faster
hd_bytes[3-diff] 0.0001ms 0.0001ms 1.0% faster
hd_bytes[3-same] 0.0001ms 0.0001ms 0.5% faster
hd_bytes[64-diff] 0.0001ms 0.0001ms 0.3% faster
hd_bytes_buffer[bytearray] 0.0001ms 0.0001ms 2.2% faster
hd_bytes_buffer[memoryview] 0.0001ms 0.0001ms 1.3% slower
hd_bytes_gil_boundary[16376] 0.0002ms 0.0002ms 17.7% slower
hd_bytes_gil_boundary[16384] 0.0003ms 0.0003ms 18.5% slower
hd_bytes_gil_boundary[16392] 0.0003ms 0.0004ms 57.3% slower
hd_bytes_random[1024] 0.0001ms 0.0001ms 1.8% faster
hd_bytes_random[16] 0.0001ms 0.0001ms 0.3% slower
hd_bytes_random[64] 0.0001ms 0.0001ms 0.0% faster
hd_string[1000-diff] 0.0001ms 0.0001ms 0.2% faster
hd_string[1000-same] 0.0001ms 0.0001ms 0.7% slower
hd_string[1024-diff] 0.0001ms 0.0001ms 2.0% faster
hd_string[1024-same] 0.0001ms 0.0001ms 0.5% slower
hd_string[3-diff] 0.0001ms 0.0001ms 2.2% faster
hd_string[3-same] 0.0001ms 0.0001ms 0.9% faster
hd_string[64-diff] 0.0001ms 0.0001ms 3.8% faster
hd_string_random[1024] 0.0001ms 0.0002ms 80.7% slower
hd_string_random[16] 0.0001ms 0.0001ms 4.7% faster
hd_string_random[64] 0.0001ms 0.0001ms 4.0% faster
stdlib_bytes_distance_random[1024] 0.0023ms 0.0022ms 0.4% faster
stdlib_bytes_distance_random[16] 0.0003ms 0.0004ms 0.3% slower
stdlib_bytes_distance_random[64] 0.0004ms 0.0004ms 0.1% slower
stdlib_hex_distance_random[1024] 0.0028ms 0.0028ms 0.0% slower
stdlib_hex_distance_random[16] 0.0002ms 0.0002ms 0.0% slower
stdlib_hex_distance_random[64] 0.0003ms 0.0003ms 0.1% slower

Legend: ✅ Faster (>5%) · ⚠️ Slower (5-30%) · ❌ Regression (>30%) · 🆕 New · 🗑️ Removed

@mrecachinas
mrecachinas force-pushed the perf/pyo3-pass-module branch 3 times, most recently from f8056ee to 73c0b0b Compare September 23, 2026 02:08
…l specialization

PyO3 tags every `#[pyfunction]` without `pass_module` as METH_STATIC
(ml_flags 0xa2). CPython 3.14 still specializes calls to them as
CALL_BUILTIN_FAST_WITH_KEYWORDS (the specializer masks METH_STATIC off),
but the specialized op's guard compares the full flags against
METH_FASTCALL | METH_KEYWORDS, so every call deopts to the generic
PyObject_Vectorcall path. Profiles showed `PyObject_Vectorcall` and
`cfunction_vectorcall_FASTCALL_KEYWORDS` frames only for PyO3 functions.

Taking the (unused) module drops METH_STATIC (flags 0x82). The only
Python-visible difference is `__self__` becoming the extension module and
`__text_signature__` gaining `$module`, as with CPython's own builtins
such as `len`; `inspect.signature`, keyword arguments, return values, and
error messages are unchanged (checked 168 call probes across 8 functions).

Interleaved A/B in one process (Apple M4 Max, CPython 3.14.7, min of
3 x 7 runs; call floor `operator.is_` = 11.8 ns):

| call                               | before  | after   |       |
|------------------------------------|---------|---------|-------|
| hamming_distance_string, 16 chars  | 31.9 ns | 28.9 ns | 1.11x |
| hamming_distance_string, 64 chars  | 34.0 ns | 31.3 ns | 1.09x |
| hamming_distance_bytes, 16 B       | 29.1 ns | 26.4 ns | 1.11x |
| hamming_distance_bytes, 64 B       | 33.3 ns | 29.7 ns | 1.12x |
| hamming_distance_bytes, bytearray  | 49.7 ns | 47.0 ns | 1.06x |
| check_hexstrings_within_dist, 16   | 34.9 ns | 31.2 ns | 1.12x |
| check_bytes_within_dist, 16 B      | 31.1 ns | 28.1 ns | 1.11x |
| set_algo                           | 36.8 ns | 31.5 ns | 1.17x |

Adds a regression test that every exported function is bound to the
extension module; it fails without this change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c7edd725-5714-4044-acf4-c9afc6ec8cf8
@mrecachinas
mrecachinas merged commit fbab043 into main Sep 23, 2026
31 checks passed
@mrecachinas
mrecachinas deleted the perf/pyo3-pass-module branch September 23, 2026 13:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant