8000 runtimes · adamtheturtle/pythoncapi@1495342 · GitHub
[go: up one dir, main page]
Skip to content

Commit 1495342

Browse files
vstinnervstinner
committed
runtimes
1 parent c0d42ce commit 1495342

File tree

4 files changed

+109
-0
lines changed

4 files changed

+109
-0
lines changed

‎doc/backward_compatibility.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _back-compat:
2+
13
++++++++++++++++++++++
24
Backward compatibility
35
++++++++++++++++++++++

‎doc/index.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,26 @@ Design a new better C API for Python
44

55
Subtitle: "Make the stable API usable".
66

7+
To be able to introduce backward incompatible changes to the C API without
8+
breaking too many C extensions, this project proposes two things: design a
9+
:ref:`helper layer <back-compat>` providing :ref:`removed functions
10+
<remove-funcs>`, and a new :ref:`Python runtime <runtimes>` which is only
11+
usable with C extensions compiled with the new stricter and smaller C API (and
12+
the new :ref:`stable ABI
13+
<stable-abi>`).
14+
715
Pages
816
=====
917

1018
.. toctree::
1119
:maxdepth: 2
1220

1321
roadmap
22+
runtimes
1423
bad_api
1524
c_api
1625
private_c_api
26+
remove_functions
1727
backward_compatibility
1828
calling_conventions
1929
stable_abi

‎doc/remove_functions.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _remove-funcs:
2+
13
++++++++++++++++++++++++++++++++++++++
24
Remove functions from the Python C API
35
++++++++++++++++++++++++++++++++++++++

‎doc/runtimes.rst

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
+++++++++++++++
2+
Python runtimes
3+
+++++++++++++++
4+
5+
To be able to implement :ref:`backward compatibility <back-compat>`, the plan
6+
is to provide multiple Python runtimes, at least two. An "old" runtime with
7+
maximum backward compatibility, and one "new" runtime which includes
8+
experimental new changes but requires using the newer C API.
9+
10+
Runtimes
11+
========
12+
13+
Regular Python: /usr/bin/python3
14+
--------------------------------
15+
16+
* Python compiled in release mode
17+
* This runtime still provides ``Py_INCREF()`` macro:
18+
modify ``PyObject.ob_refcnt`` at the ABI level.
19+
* Compatible with Python 3.7 C **API**.
20+
* Should be compatible with Python 3.7 **ABI**.
21+
22+
Compared to Python 3.7 regular runtime, this runtime no longer check its
23+
arguments. The debug runtime should now be preferred to develop C extensions
24+
and to run tests.
25+
26+
Example of Python 3.7 code::
27+
28+
int
29+
PyList_Append(PyObject *op, PyObject *newitem)
30+
{
31+
if (PyList_Check(op) && (newitem != NULL))
32+
return app1((PyListObject *)op, newitem);
33+
PyErr_BadInternalCall();
34+
return -1;
35+
}
36+
37+
The ``if (PyList_Check(op) && (newitem != NULL))`` belongs to the debug runtime
38+
and should be removed from the regular Python.
39+
40+
Debug runtime: /usr/bin/python3-dbg
41+
-----------------------------------
42+
43+
* Compatible with Python 3.7 C **API**.
44+
* Compatible with regular runtime 3.8 **ABI**, but **not compatible**
45+
with regular runtime 3.7 ABI.
46+
* CPython compiled with ``./configure --with-pydebug``
47+
* Provide ``sys.gettotalrefcount()`` which allows to check for reference leaks.
48+
* C function calls check most arguments: check type, value range, etc.
49+
* Runtime compiled with C assertion: crash (kill itself with SIGABRT signal)
50+
if a C assertion fails (``assert(...);``).
51+
* Use the debug hooks on memory allocators by default, as ``PYTHONDEBUG=debug``
52+
environment variable: detect memory under- and overflow and misusage of
53+
memory allocators.
54+
* Compiled without compiler optimizations (``-Og`` or even ``-O0``) to be
55+
usable with a debugger like ``gdb``: python-gdb.py should work perfectly.
56+
However, the regular runtime is unusable with gdb since most variables and
57+
function arguments are stored in registers, and so gdb fails with the
58+
"<optimized out>" message.
59+
60+
Experimental runtime: experimental-python3
61+
------------------------------------------
62+
63+
* Loading a C extension compiled with Python 3.7 must fail.
64+
* Loading a C extension compiled with the Python C API 3.8 in the backward
65+
compatible mode must fail.
66+
* Only C extensions compiled with the **new** Python C API 3.8 can be loaded.
67+
You have to **opt-in** for this runtime.
68+
* Not compatible with Python 3.7 API: PyDict_GetItem() is gone,
69+
PyDict_GetItemRef() must be used instead.
70+
* Not compatible with Python 3.8 ABI: using Py_INCREF() macro uses
71+
``PyObject.ob_refcnt`` at the ABI level, whereas this field must **not** be
72+
access at the ABI level.
73+
* ``Py_GC`` header and ``PyObject`` structure can be very different from the
74+
one used by the regular and debug runtimes.
75+
76+
Technically, this experimental runtime is likely to be a opt-in compilation
77+
mode of the upstream CPython code base.
78+
79+
Your runtime
80+
------------
81+
82+
Since a :ref:`stable ABI <stable-abi>` have been designed, if all your C
83+
extensions have opt-in for the new C API: you are now allowed to fork CPython
84+
and experiment your own flavor CPython. Do whatever you want: C extensions only
85+
access your runtime through runtime.
86+
87+
PyPy, RustPython and others
88+
---------------------------
89+
90+
Since the ABI (and the C API) became smaller, you can imagine that Python
91+
implementations other than CPython will be able to more easily have a **full
92+
and up-to-date support** of the latest full C API.
93+
94+
**Welcome into the bright world of multiple new cool and compatible Python
95+
runtimes!**

0 commit comments

Comments
 (0)
0