gh-129724: gh-156504: Make marshal output independent of reference counts

[gpshead]

marshal.dumps() could give different bytes for the same value, because the writer used the reference count of each object to decide whether a later occurrence may refer back to it (FLAG_REF). The count depends on what else in the process holds a reference to the object, and on the free-threaded build on which thread owns it. This is the cause of gh-156504 and one of the two causes of gh-129724 (the other is in the compiler: see the companion PR gh-159193).

FLAG_REF is now set on exactly the objects that are written more than once in the dump.

Example

>>> x = float('1.5')
>>> marshal.dumps([float('1.5')]).hex(' ')   # refcount 1
'5b 01 00 00 00 67 00 00 00 00 00 00 f8 3f'
>>> marshal.dumps([x]).hex(' ')              # refcount 2: main sets FLAG_REF (0x80)
'5b 01 00 00 00 e7 00 00 00 00 00 00 f8 3f'

With this PR both calls return the first form. Where an object really is written twice, the index of the reference no longer counts objects that were flagged for nothing:

value: [a, b, b]          a = 1.5 and b = 2.5, both also referenced from elsewhere

main:     [ 3   FLOAT|REF 1.5   FLOAT|REF 2.5   REF #1 ]      a is flagged for nothing, so b is #1
this PR:  [ 3   FLOAT     1.5   FLOAT|REF 2.5   REF #0 ]      only b is flagged, so b is #0

How

The reader numbers the flagged objects in the order it meets them, so the writer cannot know the index of a reference until it knows which earlier objects end up flagged. It still makes a single pass over the objects, and fixes up the output at the end.

flowchart TB
  subgraph before["main"]
    direction TB
    b1["w_ref(obj)"] --> b2{"refcount == 1?"}
    b2 -- yes --> b3["write object<br>no flag"]
    b2 -- no --> b4{"seen before?"}
    b4 -- no --> b5["write object + FLAG_REF<br>index = number flagged so far"]
    b4 -- yes --> b6["write TYPE_REF index"]
  end
  subgraph after["this PR"]
    direction TB
    a1["w_ref(obj)"] --> a2{"refcount == 1?"}
    a2 -- yes --> a3["write object<br>(cannot occur twice)"]
    a2 -- no --> a4{"seen before?"}
    a4 -- no --> a5["write object, no flag yet<br>remember offset of its type byte"]
    a4 -- yes --> a6["mark object shared<br>write TYPE_REF + provisional index<br>remember its position"]
    a5 --> a7
    a6 --> a7["w_resolve_refs(), once, at the end:<br>set FLAG_REF on shared objects,<br>number them, rewrite TYPE_REF indexes"]
  end

Loading

• A reference count of 1 is still used, but only as a shortcut to skip the hash table: such an object cannot occur twice, so the result is the same without it.
• Interned strings are no longer flagged unconditionally.
• The reader is unchanged and the format version is not bumped. Old and new readers load old and new output.
• PyMarshal_WriteObjectToFile() now builds the data in memory and writes it with one fwrite(), since the flags are only known at the end. Nothing is written if the object cannot be marshalled. Documented in Doc/c-api/marshal.rst.

Compatibility

The bytes of every .pyc change (fewer flags), which is why Programs/test_frozenmain.h is regenerated. marshal.loads() gives the same objects with the same sharing.

The generated pycs can be loaded by prior Python versions, but this kind of change might be considered disruptive for some when considering a backport. Realistically: prior versions are all "broken" by not producing stable output in real world scenarios, so any bug fixes going in that stabilize how things work are going to lead to some newly generated bytecode changing vs what was seen in the past, as already happens between runs compiling the same source file under different process state today.

Related: #159197 is stacked on top of this.

Performance

Release builds, not PGO, compared with main:

	default (GIL)	free-threaded
dumps of the code objects of the stdlib	3.7% slower	4.3% slower
dumps dominated by references (millions of TYPE_REF)	5-9% slower
dumps of unshared data (1M distinct floats)	32% faster
loads of the new output	3-5% faster

Writer memory grows by 8 bytes per object with a reference count above 1.

Tests

ReferenceTestCase in test_marshal checks exact bytes: single occurrences are not flagged whatever their reference count, interned strings, references at every buffer offset, objects seen before and after the ones they share with, NaNs in sets. test_capi.test_marshal checks that nothing is written on error.

---

drafted using Claude, reviewed & iterated upon by me.

Fixes #156504

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35107691 | 📁 Comparing d69021e against main (e878e1e)

  🔍 Preview build  

12 files changed · ± 12 modified

± Modified

• builtins/stdtypes.html
• c-api/marshal.html
• library/concurrent.interpreters.html
• library/ctypes.html
• library/multiprocessing.html
• library/tarfile.html
• reference/expressions.html
• using/android.html
• using/ios.html
• using/mac.html
• and 2 more...

[bedevere-bot]

🤖 New build scheduled with the buildbot fleet by @gpshead for commit 355cb8c 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F159192%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-buildbots label again.

[bedevere-bot]

🤖 New build scheduled with the buildbot fleet by @gpshead for commit 7893950 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F159192%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-buildbots label again.

[methane]

Could you reduce the number of NEWS entries to one or two? In What's New, the C API and library changes need to be documented separately because they are in different sections, but I think related changes can be combined into a single NEWS entry.

[gpshead]

ETOOMUCHNEWS - good call, done.

[bedevere-app]

GH-159290 is a backport of this pull request to the 3.15 branch.