GH-140052: Add PyTuple_MakeSingle and PyTuple_MakePair

[sergey-miryanov]

As requested by @vstinner I have added a separate PR with two functions: PyTuple_MakeSingle and PyTuple_MakePair.

• Issue: [C API] Replace PyTuple_Pack(1,2) with PyTuple_Make[Single,Pair] to optimize creation of tuples #140052

---

📚 Documentation preview 📚: https://cpython-previews--140132.org.readthedocs.build/

[sergey-miryanov]

@vstinner I have made requested changes. Please take a look.

[sergey-miryanov]

Done, please take a look.

[sergey-miryanov]

Microbenchmarks:
Windows 11, i5-11600K @ 3.90GHz

+----------------+---------+-----------------+-----------------------+-----------------------+-----------------------+
| Benchmark      | t       | s               | p                     | a                     | m                     |
+================+=========+=================+=======================+=======================+=======================+
| tuple-1        | 12.8 ns | not significant | 12.2 ns: 1.06x faster | 12.4 ns: 1.04x faster | 11.8 ns: 1.09x faster |
+----------------+---------+-----------------+-----------------------+-----------------------+-----------------------+
| tuple-2        | 14.5 ns | not significant | 13.3 ns: 1.09x faster | 13.2 ns: 1.10x faster | 12.3 ns: 1.18x faster |
+----------------+---------+-----------------+-----------------------+-----------------------+-----------------------+
| Geometric mean | (ref)   | 1.01x slower    | 1.07x faster          | 1.07x faster          | 1.13x faster          |
+----------------+---------+-----------------+-----------------------+-----------------------+-----------------------+

Ubuntu 24.04, gcc (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0, same cpu, built with lto enabled

+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| Benchmark      | t       | s                     | p                     | a                     | m                     |
+================+=========+=======================+=======================+=======================+=======================+
| tuple-1        | 15.7 ns | 14.5 ns: 1.08x faster | 12.7 ns: 1.24x faster | 11.5 ns: 1.36x faster | 11.2 ns: 1.40x faster |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| tuple-2        | 22.6 ns | 20.1 ns: 1.12x faster | 16.0 ns: 1.41x faster | 14.2 ns: 1.59x faster | 15.0 ns: 1.51x faster |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| Geometric mean | (ref)   | 1.10x faster          | 1.32x faster          | 1.47x faster          | 1.45x faster          |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+

t - PyTuple_New + PyTuple_SetItem
s - PyTuple_New + PyTuple_SET_ITEM
p - PyTuple_Pack
a - PyTuple_FromArray
m - PyTuple_Make[Single,Pair]

Microbenchmarks - sergey-miryanov@07f7c6a

run scripts

bench_tuple.py

import pyperf
import _testcapi
import functools
runner = pyperf.Runner()
for size in (1, 2):
    func = functools.partial(_testcapi.bench_tuple, size)
    runner.bench_time_func(f'tuple-{size}', func)

bench_steal.py

import pyperf
import _testcapi
import functools
runner = pyperf.Runner()
for size in (1, 2):
    func = functools.partial(_testcapi.bench_tuple_steal, size)
    runner.bench_time_func(f'tuple-{size}', func)

bench_pack.py

import pyperf
import _testcapi
import functools
runner = pyperf.Runner()
for size in (1, 2):
    func = functools.partial(_testcapi.bench_tuple_pack, size)
    runner.bench_time_func(f'tuple-{size}', func)

bench_from_array.py

import pyperf
import _testcapi
import functools
runner = pyperf.Runner()
for size in (1, 2):
    func = functools.partial(_testcapi.bench_tuple_from_array, size)
    runner.bench_time_func(f'tuple-{size}', func)

bench_make.py

import pyperf
import _testcapi
import functools
runner = pyperf.Runner()
for size in (1, 2):
    func = functools.partial(_testcapi.bench_tuple_make, size)
    runner.bench_time_func(f'tuple-{size}', func)

[eendebakpt]

In the microbenchmarks it seems odd that PyTuple_Pack is faster than PyTuple_New + PyTuple_SET_ITEM. I can think of no reasons for this. Which optimization settings did you use? Looking at the implementation of the microbenchmarks: maybe for PyTuple_Pack the code PyObject *one = PyLong_FromLong(0); is optimized away. What happens if you move the PyLong_FromLong outside the loop?

[sergey-miryanov]

Microbenchmark results from Windows machine (Windows 11, i5-11600K @ 3.90GHz)
Results for Tuple(Long) and Tuple(Long, Long) - tuple will not be tracked.

+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| Benchmark      | n       | s                     | p                     | a                     | m                     |
+================+=========+=======================+=======================+=======================+=======================+
| tuple-1        | 14.1 ns | not significant       | 9.79 ns: 1.44x faster | 9.39 ns: 1.50x faster | 8.62 ns: 1.64x faster |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| tuple-2        | 15.7 ns | 16.1 ns: 1.02x slower | 12.3 ns: 1.28x faster | 13.1 ns: 1.20x faster | 12.1 ns: 1.30x faster |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| Geometric mean | (ref)   | 1.01x slower          | 1.36x faster          | 1.34x faster          | 1.46x faster          |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+

Results for Tuple(EmptyTuple) and Tuple(EmptyTuple, EmptyTuple) - tuple will be tracked (EmptyTuple - is a special case - we don't allocate it)

+----------------+---------+-----------------------+-----------------------+-----------------+-----------------------+
| Benchmark      | tn      | ts                    | tp                    | ta              | tm                    |
+================+=========+=======================+=======================+=================+=======================+
| tuple-1        | 14.4 ns | not significant       | 14.1 ns: 1.02x faster | not significant | 13.9 ns: 1.04x faster |
+----------------+---------+-----------------------+-----------------------+-----------------+-----------------------+
| tuple-2        | 15.1 ns | 15.7 ns: 1.04x slower | 16.0 ns: 1.06x slower | not significant | 14.5 ns: 1.04x faster |
+----------------+---------+-----------------------+-----------------------+-----------------+-----------------------+
| Geometric mean | (ref)   | 1.02x slower          | 1.02x slower          | 1.00x slower    | 1.04x faster          |
+----------------+---------+-----------------------+-----------------------+-----------------+-----------------------+

Notes:

1. We can see a significant effect of tracking and not tracking of tuples.
2. We can see that version with PyTuple_Make[Single, Pair] much better for not trackable tuples, and get not much gain for trackable ones.
3. We can see that SET_ITEM version is slower than SetItem one, I don't understand why.

Linux benchmarks will be a bit later.

Benchmarks here - https://github.com/sergey-miryanov/cpython/tree/140052-pytuple-make-pair-bench

[vstinner]

I don't know how to read your benchmark. What are the "a", "p", "s", etc. columns?

[vstinner]

Oh, I suppose that letters are the same from previous benchmark: #140132 (comment)

[sergey-miryanov]

Yes, they are the same (except n then in new benchmarks means PyTuple_New + PyTuple_SetItem).
Sorry.

n - PyTuple_New + PyTuple_SetItem
s - PyTuple_New + PyTuple_SET_ITEM
p - PyTuple_Pack
a - PyTuple_FromArray
m - PyTuple_Make[Single,Pair]

tn, ts, tp, ta, tm - for version where internal tuple's item is an EmptyTuple.

[sergey-miryanov]

Microbenchmark results from Linux (Ubuntu 24.04, gcc (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0, i5-11600K @ 3.90GHz)
Results for Tuple(Long) and Tuple(Long, Long) - tuple will not be tracked.

+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| Benchmark      | n       | s                     | p                     | a                     | m                     |
+================+=========+=======================+=======================+=======================+=======================+
| tuple-1        | 11.9 ns | 11.8 ns: 1.01x faster | 9.26 ns: 1.29x faster | 8.37 ns: 1.43x faster | 8.70 ns: 1.37x faster |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| tuple-2        | 17.2 ns | 16.5 ns: 1.04x faster | 12.6 ns: 1.37x faster | 11.1 ns: 1.56x faster | 10.7 ns: 1.60x faster |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| Geometric mean | (ref)   | 1.03x faster          | 1.33x faster          | 1.49x faster          | 1.48x faster          |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+

Results for Tuple(EmptyTuple) and Tuple(EmptyTuple, EmptyTuple):

+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| Benchmark      | tn      | ts                    | tp                    | ta                    | tm                    |
+================+=========+=======================+=======================+=======================+=======================+
| tuple-1        | 12.7 ns | 12.2 ns: 1.04x faster | 10.9 ns: 1.17x faster | 9.70 ns: 1.31x faster | 9.94 ns: 1.28x faster |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| tuple-2        | 18.1 ns | 17.4 ns: 1.04x faster | 13.8 ns: 1.31x faster | 11.6 ns: 1.56x faster | 12.0 ns: 1.51x faster |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+
| Geometric mean | (ref)   | 1.04x faster          | 1.24x faster          | 1.43x faster          | 1.39x faster          |
+----------------+---------+-----------------------+-----------------------+-----------------------+-----------------------+v

Notes:

1. On Linux I see that tracking and not tracking of the tuples doesn't have much difference.
2. Version with PyTuple_Make[Single,Pair] is a bit slower than version with PyTuple_FromArray, I suspect it is because PyTuple_Make[Single,Pair] are not covered by PGO + LTO.
3. Build params:

./configure --enable-optimizations --with-lto=full --prefix=/home/msn/work/cpython/installed/tuple-make-pair-bench

Legend:

n - PyTuple_New + PyTuple_SetItem
s - PyTuple_New + PyTuple_SET_ITEM
p - PyTuple_Pack
a - PyTuple_FromArray
m - PyTuple_Make[Single,Pair]

tn, ts, tp, ta, tm - for version where internal tuple's item is an EmptyTuple.

[sergey-miryanov]

@eendebakpt I have updated microbenchmarks. Could you please take a look? Are they fair enough now?

[sergey-miryanov]

@vstinner This is ready for review. Could you please take a look?

[efimov-mikhail]

IMO, it'll be better not to check this, since we can make another decision in the future.

[sergey-miryanov]

We have a small disagreement here.
I think we should explicitly fix the current behavior in the tests.
@efimov-mikhail does not want to fix the behavior that may change in the near future because doing so would require changes to the tests.

We need another opinion on this.

[eendebakpt]

@eendebakpt I have updated microbenchmarks. Could you please take a look? Are they fair enough now?

The benchmarks seem fine, although I still find the results surprising (why is PyTuple_Pack faster than PyTuple_New + PyTuple_SET_ITEM? maybe it depends on whether the object one you are adding in the performance tests is not tracked by the GC).

But I am +1 on the PR, even if we don't go looking into tiny performance details: the methods PyTuple_MakeSingle/PyTuple_MakePair have a clean interface, they can be used quite a bit in the codebase and are faster than the alternative PyTuple_Pack.

[vstinner]

I created capi-workgroup/decisions#84 decision issue for the C API Working Group.