PEP 744: Add Discussions-To and Post-History (#3752)

* Add discussion links, and inline make links anonymous

* Fix links

Author: brandtbucher

peps/pep-0744.rst

@@ -1,16 +1,18 @@
 PEP: 744
 Title: JIT Compilation
 Author: Brandt Bucher <[email protected]>
+Discussions-To: https://discuss.python.org/t/pep-744-jit-compilation/50756
 Status: Draft
 Type: Informational
 Created: 11-Apr-2024
 Python-Version: 3.13
+Post-History: `11-Apr-2024 <https://discuss.python.org/t/pep-744-jit-compilation/50756>`__
 
 Abstract
 ========
 
 Earlier this year, an `experimental "just-in-time" compiler
-<https://github.com/python/cpython/pull/113465>`_ was merged into CPython's
+<https://github.com/python/cpython/pull/113465>`__ was merged into CPython's
 ``main`` development branch. While recent CPython releases have included other
 substantial internal changes, this addition represents a particularly
 significant departure from the way CPython has traditionally executed Python
@@ -27,22 +29,22 @@ introduction.
 Readers interested in learning more about the new JIT are encouraged to consult
 the following resources:
 
-- The `presentation <https://youtu.be/HxSHIpEQRjs>`_ which first introduced the
+- The `presentation <https://youtu.be/HxSHIpEQRjs>`__ which first introduced the
   JIT at the 2023 CPython Core Developer Sprint. It includes relevant
   background, a light technical introduction to the "copy-and-patch" technique
   used, and an open discussion of its design amongst the core developers
   present.
 
-- The `open access paper <https://dl.acm.org/doi/10.1145/3485513>`_ originally
+- The `open access paper <https://dl.acm.org/doi/10.1145/3485513>`__ originally
   describing copy-and-patch.
 
-- The `blog post <https://sillycross.github.io/2023/05/12/2023-05-12>`_ by the
+- The `blog post <https://sillycross.github.io/2023/05/12/2023-05-12>`__ by the
   paper's author detailing the implementation of a copy-and-patch JIT compiler
   for Lua. While this is a great low-level explanation of the approach, note
   that it also incorporates other techniques and makes implementation decisions
   that are not particularly relevant to CPython's JIT.
 
-- The `implementation <#reference-implementation>`_ itself.
+- The `implementation <#reference-implementation>`__ itself.
 
 Motivation
 ==========
@@ -53,7 +55,7 @@ direct translation of the source code: it is untyped, and largely unoptimized.
 
 Since the Python 3.11 release, CPython has used a "specializing adaptive
 interpreter" (:pep:`659`), which `rewrites these bytecode instructions in-place
-<https://youtu.be/shQtrn1v7sQ>`_ with type-specialized versions as they run.
+<https://youtu.be/shQtrn1v7sQ>`__ with type-specialized versions as they run.
 This new interpreter delivers significant performance improvements, despite the
 fact that its optimization potential is limited by the boundaries of individual
 bytecode instructions. It also collects a wealth of new profiling information:
@@ -63,7 +65,7 @@ what paths through the program are being executed the most. In other words,
 
 Since the Python 3.12 release, CPython has generated this interpreter from a
 `C-like domain-specific language
-<https://github.com/python/cpython/blob/main/Python/bytecodes.c>`_ (DSL). In
+<https://github.com/python/cpython/blob/main/Python/bytecodes.c>`__ (DSL). In
 addition to taming some of the complexity of the new adaptive interpreter, the
 DSL also allows CPython's maintainers to avoid hand-writing tedious boilerplate
 code in many parts of the interpreter, compiler, and standard library that must
@@ -98,7 +100,7 @@ Since much of this data varies even between identical runs of a program and the
 existing optimization pipeline makes heavy use of runtime profiling information,
 it doesn't make much sense to compile these traces ahead of time. As has been
 demonstrated for many other dynamic languages (`and even Python itself
-<https://www.pypy.org>`_), the most promising approach is to compile the
+<https://www.pypy.org>`__), the most promising approach is to compile the
 optimized micro-ops "just in time" for execution.
 
 Rationale
@@ -168,7 +170,7 @@ Support
 The JIT has been developed for all of :pep:`11`'s current tier one platforms,
 most of its tier two platforms, and one of its tier three platforms.
 Specifically, CPython's ``main`` branch has `CI
-<https://github.com/python/cpython/blob/main/.github/workflows/jit.yml>`_
+<https://github.com/python/cpython/blob/main/.github/workflows/jit.yml>`__
 building and testing the JIT for both release and debug builds on:
 
 - ``aarch64-apple-darwin/clang``
@@ -202,7 +204,7 @@ failures on tier one and tier two platforms should block releases. Though it's
 not necessary to update :pep:`11` to specify JIT support, it may be helpful to
 do so anyway. Otherwise, a list of supported platforms should be maintained in
 `the JIT's README
-<https://github.com/python/cpython/blob/main/Tools/jit/README.md>`_.
+<https://github.com/python/cpython/blob/main/Tools/jit/README.md>`__.
 
 Since it should always be possible to build CPython without the JIT, removing
 JIT support for a platform should *not* be considered a backwards-incompatible
@@ -253,7 +255,7 @@ This JIT, like any JIT, produces large amounts of executable data at runtime.
 This introduces a potential new attack surface to CPython, since a malicious
 actor capable of influencing the contents of this data is therefore capable of
 executing arbitrary code. This is a `well-known vulnerability
-<https://en.wikipedia.org/wiki/Just-in-time_compilation#Security>`_ of JIT
+<https://en.wikipedia.org/wiki/Just-in-time_compilation#Security>`__ of JIT
 compilers.
 
 In order to mitigate this risk, the JIT has been written with best practices in
@@ -282,7 +284,7 @@ Apple Silicon
 Though difficult to test without actually signing and packaging a macOS release,
 it *appears* that macOS releases should `enable the JIT Entitlement for the
 Hardened Runtime
-<https://developer.apple.com/documentation/apple-silicon/porting-just-in-time-compilers-to-apple-silicon#Enable-the-JIT-Entitlement-for-the-Hardened-Runtime>`_.
+<https://developer.apple.com/documentation/apple-silicon/porting-just-in-time-compilers-to-apple-silicon#Enable-the-JIT-Entitlement-for-the-Hardened-Runtime>`__.
 
 This shouldn't make *installing* Python any harder, but may add additional steps
 for release managers to perform.
@@ -322,7 +324,7 @@ Choose the sections that best describe you:
 
   - ...if you don't wish to build the JIT, you can simply ignore it. Otherwise,
     you will need to `install a compatible version of LLVM
-    <https://github.com/python/cpython/blob/main/Tools/jit/README.md>`_, and
+    <https://github.com/python/cpython/blob/main/Tools/jit/README.md>`__, and
     pass the appropriate flag to the build scripts. Your build may take up to a
     minute longer. Note that the JIT should *not* be distributed to end users or
     used in production while it is still in the experimental phase.
@@ -446,7 +448,7 @@ Support multiple compiler toolchains
 Clang is specifically needed because it's the only C compiler with support for
 guaranteed tail calls (|musttail|_), which are required by CPython's
 `continuation-passing-style
-<https://en.wikipedia.org/wiki/Continuation-passing_style#Tail_calls>`_ approach
+<https://en.wikipedia.org/wiki/Continuation-passing_style#Tail_calls>`__ approach
 to JIT compilation. Without it, the tail-recursive calls between templates could
 result in unbounded C stack growth (and eventual overflow).
 
@@ -481,7 +483,7 @@ Add GPU support
 
 The JIT is currently CPU-only. It does not, for example, offload NumPy array
 computations to CUDA GPUs, as JITs like `Numba
-<https://numba.pydata.org/numba-doc/latest/cuda/overview.html>`_ do.
+<https://numba.pydata.org/numba-doc/latest/cuda/overview.html>`__ do.
 
 There is already a rich ecosystem of tools for accelerating these sorts of
 specialized tasks, and CPython's JIT is not intended to replace them. Instead,
@@ -495,12 +497,12 @@ Speed
 -----
 
 Currently, the JIT is `about as fast as the existing specializing interpreter 
-<https://github.com/faster-cpython/benchmarking-public/blob/main/configs.png>`_
+<https://github.com/faster-cpython/benchmarking-public/blob/main/configs.png>`__
 on most platforms. Improving this is obviously a top priority at this point,
 since providing a significant performance gain is the entire motivation for
 having a JIT at all. A number of proposed improvements are already underway, and
 this ongoing work is being tracked in `GH-115802
-<https://github.com/python/cpython/issues/115802>`_.
+<https://github.com/python/cpython/issues/115802>`__.
 
 Memory
 ------
@@ -509,7 +511,7 @@ Because it allocates additional memory for executable machine code, the JIT does
 use more memory than the existing interpreter at runtime. According to the
 official benchmarks, the JIT currently uses about `10-20% more memory than the
 base interpreter
-<https://github.com/faster-cpython/benchmarking-public/blob/main/memory_configs.png>`_.
+<https://github.com/faster-cpython/benchmarking-public/blob/main/memory_configs.png>`__.
 The upper end of this range is due to ``aarch64-apple-darwin``, which has larger
 page sizes (and thus, a larger minimum allocation granularity).
 
@@ -522,7 +524,7 @@ likely to be a real concern.
 Not much effort has been put into optimizing the JIT's memory usage yet, so
 these numbers likely represent a maximum that will be reduced over time.
 Improving this is a medium priority, and is being tracked in `GH-116017
-<https://github.com/python/cpython/issues/116017>`_.
+<https://github.com/python/cpython/issues/116017>`__.
 
 Earlier versions of the JIT had a more complicated memory allocation scheme
 which imposed a number of fragile limitations on the size and layout of the
@@ -547,7 +549,7 @@ since installing the required tools is not prohibitively difficult for most
 people building CPython, and the build step is not particularly time-consuming.
 
 Since some still remain interested in this possibility, discussion is being
-tracked in `GH-115869 <https://github.com/python/cpython/issues/115869>`_.
+tracked in `GH-115869 <https://github.com/python/cpython/issues/115869>`__.
 
 Footnotes
 =========