Skip to content

Increase int digit count available in freelists #162150

Open

Description

@cmaloney

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:

Linked PRs

Activity

  1. self-assigned this
    on Nov 17, 2026
  2. added
    type-featureA feature request or enhancement
    performancePerformance or resource usage
    interpreter-core(Objects, Python, Grammar, and Parser dirs)
    on Nov 17, 2026
  3. eendebakpt commented on Nov 17, 2026

    @eendebakpt
    Contributor

    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.

  4. cmaloney commented on Nov 17, 2026

    @cmaloney
    ContributorAuthor

    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.

  5. cmaloney commented on Nov 17, 2026

    @cmaloney
    ContributorAuthor

    experimental commit for Proposal 1: cmaloney@87ea9e2

  6. eendebakpt commented on Nov 17, 2026

    @eendebakpt
    Contributor

    experimental commit for Proposal 1: cmaloney@87ea9e2

    Is the long_fits_freelist a 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 just ndigits <= MAX_DIGITS_FOR_FREELIST.

  7. cmaloney commented on Nov 17, 2026

    @cmaloney
    ContributorAuthor

    Yep, compiler optimizes away. Moving to MAX_DIGITS_FOR_FREELIST optimizes away even better as then the constant is fully isolated. gh-162173

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

interpreter-core(Objects, Python, Grammar, and Parser dirs)performancePerformance or resource usagetype-featureA feature request or enhancement

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions