cpython/InternalDocs
Petr Viktorin 6f1d448bc1
gh-113993: Allow interned strings to be mortal, and fix related issues (GH-120520)
* Add an InternalDocs file describing how interning should work and how to use it.

* Add internal functions to *explicitly* request what kind of interning is done:
  - `_PyUnicode_InternMortal`
  - `_PyUnicode_InternImmortal`
  - `_PyUnicode_InternStatic`

* Switch uses of `PyUnicode_InternInPlace` to those.

* Disallow using `_Py_SetImmortal` on strings directly.
  You should use `_PyUnicode_InternImmortal` instead:
  - Strings should be interned before immortalization, otherwise you're possibly
    interning a immortalizing copy.
  - `_Py_SetImmortal` doesn't handle the `SSTATE_INTERNED_MORTAL` to
    `SSTATE_INTERNED_IMMORTAL` update, and those flags can't be changed in
    backports, as they are now part of public API and version-specific ABI.

* Add private `_only_immortal` argument for `sys.getunicodeinternedsize`, used in refleak test machinery.

* Make sure the statically allocated string singletons are unique. This means these sets are now disjoint:
  - `_Py_ID`
  - `_Py_STR` (including the empty string)
  - one-character latin-1 singletons

  Now, when you intern a singleton, that exact singleton will be interned.

* Add a `_Py_LATIN1_CHR` macro, use it instead of `_Py_ID`/`_Py_STR` for one-character latin-1 singletons everywhere (including Clinic).

* Intern `_Py_STR` singletons at startup.

* For free-threaded builds, intern `_Py_LATIN1_CHR` singletons at startup.

* Beef up the tests. Cover internal details (marked with `@cpython_only`).

* Add lots of assertions

Co-Authored-By: Eric Snow <ericsnowcurrently@gmail.com>
2024-06-21 17:19:31 +02:00
..
README.md gh-119786: move locations doc to InternalDocs (#120445) 2024-06-19 17:58:54 +01:00
adaptive.md gh-119786: move adaptive interpreter doc from Python to InternalsDoc (#120137) 2024-06-06 10:56:58 +00:00
compiler.md Fix typos in documentation (#120338) 2024-06-12 12:24:43 +00:00
exception_handling.md gh-119786: add links to code in exception handling doc (#120077) 2024-06-05 16:28:47 +01:00
locations.md gh-119786: move locations doc to InternalDocs (#120445) 2024-06-19 17:58:54 +01:00
string_interning.md gh-113993: Allow interned strings to be mortal, and fix related issues (GH-120520) 2024-06-21 17:19:31 +02:00

README.md

CPython Internals Documentation

The documentation in this folder is intended for CPython maintainers. It describes implementation details of CPython, which should not be assumed to be part of the Python language specification. These details can change between any two CPython versions and should not be assumed to hold for other implementations of the Python language.

The core dev team attempts to keep this documentation up to date. If it is not, please report that through the issue tracker.

Compiler Design

Adaptive Instruction Families

The Source Code Locations Table

Exception Handling