adamtheturtle
diff --git a/‎doc/new_api.rst
Lines changed: 66 additions & 0 deletions b/‎doc/new_api.rst
Lines changed: 66 additions & 0 deletions
diff --git a/‎doc/roadmap.rst
Lines changed: 8 additions & 5 deletions b/‎doc/roadmap.rst
Lines changed: 8 additions & 5 deletions
diff --git a/‎doc/runtimes.rst
Lines changed: 17 additions & 12 deletions b/‎doc/runtimes.rst
Lines changed: 17 additions & 12 deletions
@@ -11,9 +11,17 @@ Design goals
   to be able to use the new C API on the maximum number of existing C
   extensions which use directly the C API.
 * Hide most CPython implementation details. The exact list has to be written.
+  One required change is to replace macros with functions calls. The option
+  question remains if it will be possible to replace ``Py_INCREF()`` and
+  ``Py_DECREF()`` with function calls without killing performances.
 * Reduce the size of the C API to reduce the maintenance burden of :ref:`Python
   implementations other than CPython <other-python-impl>`. See :ref:`Remove
   functions <remove-funcs>`.
+* Reduce the size of the ABI, especially export less symbols.
+
+The :ref:`backward compatibility <back-compat>` issue is partially solved by
+keeping the existing :ref:`old C API <c-api>` available as an opt-in option:
+see the :ref:`Regular runtime <regular-runtime>`.
 
 Non-goal
 ========
@@ -22,3 +30,61 @@ Non-goal
   intent to replace Cython. Moreover, there is no intent to make Cython
   development harder. Cython will still be able to access directly the full C
   API which includes implementation details and low-level "private" APIs.
+
+Hide implementation details
+===========================
+
+What are implementation details?
+--------------------------------
+
+"Implementation details" is not well specified at this point, but maybe hiding
+implementation can be done incrementally.
+
+The PEP 384 "Defining a Stable ABI" is a very good stable to find the borders
+between the public C API and implementation details: see :ref:`Stable ABI
+<stable-abi>`.
+
+Replace macros with function calls
+----------------------------------
+
+Replacing macros with functions calls is one part of the practical solution.
+For example::
+
+    #define PyList_GET_ITEM(op, i) ((PyListObject *)op)->ob_item[i]
+
+would become::
+
+    #define PyList_GET_ITEM(op, i) PyList_GetItem(op, i)
+
+or maybe even::
+
+    PyObject* PyList_GET_ITEM(PyObjcet *op, PyObject *i) { return PyList_GetItem(op, i); }
+
+Adding a **new** ``PyList_GET_ITEM()`` **function** would make the ABI larger,
+whereas the ABI should become smaller.
+
+This change remains backward compatible in term of **C API**. Moreover, using
+function calls helps to make C extension backward compatible at the **ABI
+level** as well.
+
+.. _incref:
+
+Py_INCREF()
+-----------
+
+The open question remains if it will be possible to replace ``Py_INCREF()`` and
+``Py_DECREF()`` with function calls without killing performances.
+
+Hide C structures
+-----------------
+
+The most backward incompatible change is to hide fields of C structures, up to
+PyObject. To final goal will be able to hide ``PyObject.ob_refcnt`` from the
+public C API.
+
+C extensions must be modified to use functions to access fields.
+
+In the worst case, there will be no way to access to hidden field from the
+public C API. For these users, the only option will be to stick at the
+:ref:`old C API <c-api>` which remains backward compatible and still expose
+implementation details like C structure fields.
@@ -7,14 +7,17 @@ Roadmap
 
 * Step 1: Identify :ref:`Bad C API <bad-api>` and list functions that should
   be modified or even removed
-* Step 2: Add an **opt-in** new C API with these cleanups. Test :ref:`popular
+* Step 2: Add an **opt-in** :ref:`new C API <new-c-api>` with these cleanups. Test :ref:`popular
   C extensions <consumers>` to measure how much code is broken. Start to fix
-  these C extensions. Slowly involve more and more players into the game.
-* Step 3: Remove more functions. Maybe replace Py_INCREF() macro with a
-  function call. Finish to all PyObject structure. Measure the performance.
+  these C extensions by making them **forward** compatible. Slowly involve more
+  and more players into the game.
+* Step 3: :ref:`Remove more functions <remove-funcs>`. Maybe replace
+  :ref:`Py_INCREF() macro <incref>` with a function call. Finish to hide all C
+  structures especially ``PyObject.ob_refcnt``. Measure the performance.
   Decide what to do.
 * Step 4: if step 3 gone fine and most people are still ok to continue, make
-  the new C API as the default in CPython and add an option for **opt-out**.
+  the :ref:`new C API <new-c-api>` as the default in CPython and add an option
+  for **opt-out** to stick with the :ref:`old C API <c-api>`.
 
 Status
 ======
 
@@ -12,18 +12,21 @@ experimental new changes but requires using the newer C API.
 **Welcome into the bright world of multiple new cool and compatible Python
 runtimes!**
 
+.. _regular-runtime:
+
 Regular Python: /usr/bin/python3
 ================================
 
 * Python compiled in release mode
 * This runtime still provides ``Py_INCREF()`` macro:
   modify ``PyObject.ob_refcnt`` at the ABI level.
-* Compatible with Python 3.7 C **API**.
-* Should be compatible with Python 3.7 **ABI**.
+* Should be fully compatible with :ref:`Python 3.7 C API <c-api>`
+* Should be fully compatible with Python 3.7 stable **ABI** (it may become
+  incompatible with the Python 3.7 full ABI).
 
 Compared to Python 3.7 regular runtime, this runtime no longer check its
-arguments. The debug runtime should now be preferred to develop C extensions
-and to run tests.
+arguments for performance reasons. The debug runtime should now be preferred to
+develop C extensions and to run tests.
 
 Example of Python 3.7 code::
 
@@ -61,6 +64,8 @@ Debug runtime: /usr/bin/python3-dbg
   function arguments are stored in registers, and so gdb fails with the
   "<optimized out>" message.
 
+For example, the debug runtime can check that the GIL is held by the caller.
+
 .. _exp-runtime:
 
 New experimental runtime: python3-exp
@@ -79,7 +84,7 @@ New experimental runtime: python3-exp
 * ``Py_GC`` header and ``PyObject`` structure can be very different from the
   one used by the regular and debug runtimes.
 
-Technically, this experimental runtime is likely to be a opt-in compilation
+Technically, this experimental runtime can be a opt-in compilation
 mode of the upstream CPython code base.
 
 See :ref:`Optimization ideas <optim-ideas>`.
@@ -90,19 +95,19 @@ See :ref:`Optimization ideas <optim-ideas>`.
 PyPy, RustPython and others
 ===========================
 
-Since the `C API will be smaller <new-c-api>` and the `stable ABI will become
-more usable <stable-abi>`, you can imagine that Python implementations other
-than CPython will be able to more easily have a **full and up-to-date support**
-of the latest full C API.
+Since the :ref:`C API will be smaller <new-c-api>` and the :ref:`stable ABI
+will become more usable <stable-abi>`, you can imagine that Python
+implementations other than CPython will be able to more easily have a **full
+and up-to-date support** of the latest full C API.
 
 
 Put your CPython fork here!
 ===========================
 
 Since a :ref:`stable ABI <stable-abi>` have been designed, if all your C
-extensions have opt-in for the new C API: you are now allowed to fork CPython
-and experiment your own flavor CPython. Do whatever you want: C extensions only
-access your runtime through runtime.
+extensions have opt-in for the :ref:`new C API <new-c-api>`: you are now
+allowed to fork CPython and experiment your own flavor CPython. Do whatever you
+want: C extensions only calls your runtime through function calls.
 
 See :ref:`Optimization ideas <optim-ideas>`.