Repository navigation
Description
Feature or enhancement
Background
Python's int (PyLongObject) uses 30-bit "digits" to store data. For efficiency int stores its digits inline and uses freelists to avoid allocator round trips for short lived objects. int with a single digit are called "compact" and are the only case that gets a freelist currently.
Proposal 1: Use existing 64 bit padding to let 2-digit ints use freelist
Because of struct padding two digits of space are already available on 64 bit platforms. Make it so two digit int on 64-bit can use the freelist objects.
Performance: In a local test branch this makes crypto_pyaes pyperformance benchmark ~10% faster.
Proposal 2: A second freelist for 64 bit integers
64 bit integers require three digits of space. This means they currently miss the freelist. They are commonly returned by hash(str) (usually 61-63 bits) as well as showing up in APIs using nanoseconds (ex. time.time_ns() 61 bits).
Growing PyLongObject to guarantee three digits (90 bits) of space unfortunately would bump it to the next memory allocator size class.
Add a single additional freelist which can hold up to the platform specific pointer size (ex. 3 digit for 64bit) and use that.
Note this isn't a freelist for arbitrary length ints which has been proposed previously. Just keeping a second freelist which can fit pointer sized ints.
cc: @eendebakpt who added the int freelist
Has this already been discussed elsewhere?
This is a minor feature, which does not need previous discussion elsewhere
Links to previous discussion of this feature:
- Add freelist for compact int objects #126868: Added
intfreelist. The 1-digit limit was deliberate to avoid
needing a general size-based freelist (gh-126868: Add freelist for compact int objects #126865). - GH-100240: Generic freelist, applied to ints #101453: Explored generic freelists.
- Widen specialized int fast paths to full int64 range #150424: Explores more specailization around 64 bit ints.
Activity
eendebakpt commentedon Nov 17, 2026
There is a PR adding freelists for more int sizes: #129638. Performance on microbenchmarks is ok, although I suspect it will be less in the free-threading build.
There is also #158002 which might help, as it ensures that in more cases the returned int object will match the allocated size. (which will balance the freelists over different sizes)
The 64-bit integers are most important here (besides the compact ones), although depending on the implementation it might be easy to add freelists for a bit larger classes even.
cmaloney commentedon Nov 17, 2026
It would be nice to have a "if thing frequently constructed at this size" -> "here's a fast as freelist" automatically (which would remove all this special casing). In theory the memory allocator does that a bit but freelist definitely saves time over it.
For gh-129638: It's an interesting approach, thinking through the tradeoffs of one freelist with varying size objects in it... Doing one freelist which can do up to 2 digits (the current minimum PyLongObject layout), and a "always 4 digits" space (free threaded + GIL, the next allocation size; GIL could do more but one size seems good enough) feels like it would reduce risks a little. Small ints getting much larger allocations sometimes worries me. Particularly for how perf will go through all the "is compact" cases.
cmaloney commentedon Nov 17, 2026
experimental commit for Proposal 1: cmaloney@87ea9e2
eendebakpt commentedon Nov 17, 2026
Is the
long_fits_freelista runtime calculation or can the compiler optimize it away? It would be nice if we can have a constant MAX_DIGITS_FOR_FREELIST and make the check justndigits <= MAX_DIGITS_FOR_FREELIST.cmaloney commentedon Nov 17, 2026
Yep, compiler optimizes away. Moving to MAX_DIGITS_FOR_FREELIST optimizes away even better as then the constant is fully isolated. gh-162173