bpo-46841: Use *inline* caching for `BINARY_OP` (GH-31543)

1 files changed, 28 insertions, 7 deletions

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 003d798..3dac391 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -24,6 +24,12 @@ interpreter.
       Use 2 bytes for each instruction. Previously the number of bytes varied
       by instruction.
 
+   .. versionchanged:: 3.11
+      Some instructions are accompanied by one or more inline cache entries,
+      which take the form of :opcode:`CACHE` instructions. These instructions
+      are hidden by default, but can be shown by passing ``show_caches=True`` to
+      any :mod:`dis` utility.
+
 
 Example: Given the function :func:`myfunc`::
 
@@ -54,7 +60,7 @@ The bytecode analysis API allows pieces of Python code to be wrapped in a
 :class:`Bytecode` object that provides easy access to details of the compiled
 code.
 
-.. class:: Bytecode(x, *, first_line=None, current_offset=None)
+.. class:: Bytecode(x, *, first_line=None, current_offset=None, show_caches=False)
 
 
    Analyse the bytecode corresponding to a function, generator, asynchronous
@@ -74,7 +80,7 @@ code.
    disassembled code. Setting this means :meth:`.dis` will display a "current
    instruction" marker against the specified opcode.
 
-   .. classmethod:: from_traceback(tb)
+   .. classmethod:: from_traceback(tb, *, show_caches=False)
 
       Construct a :class:`Bytecode` instance from the given traceback, setting
       *current_offset* to the instruction responsible for the exception.
@@ -100,6 +106,9 @@ code.
    .. versionchanged:: 3.7
       This can now handle coroutine and asynchronous generator objects.
 
+   .. versionchanged:: 3.11
+      Added the ``show_caches`` parameter.
+
 Example::
 
     >>> bytecode = dis.Bytecode(myfunc)
@@ -153,7 +162,7 @@ operation is being performed, so the intermediate analysis object isn't useful:
       Added *file* parameter.
 
 
-.. function:: dis(x=None, *, file=None, depth=None)
+.. function:: dis(x=None, *, file=None, depth=None, show_caches=False)
 
    Disassemble the *x* object.  *x* can denote either a module, a class, a
    method, a function, a generator, an asynchronous generator, a coroutine,
@@ -183,8 +192,11 @@ operation is being performed, so the intermediate analysis object isn't useful:
    .. versionchanged:: 3.7
       This can now handle coroutine and asynchronous generator objects.
 
+   .. versionchanged:: 3.11
+      Added the ``show_caches`` parameter.
+
 
-.. function:: distb(tb=None, *, file=None)
+.. function:: distb(tb=None, *, file=None, show_caches=False)
 
    Disassemble the top-of-stack function of a traceback, using the last
    traceback if none was passed.  The instruction causing the exception is
@@ -196,9 +208,12 @@ operation is being performed, so the intermediate analysis object isn't useful:
    .. versionchanged:: 3.4
       Added *file* parameter.
 
+   .. versionchanged:: 3.11
+      Added the ``show_caches`` parameter.
+
 
-.. function:: disassemble(code, lasti=-1, *, file=None)
-              disco(code, lasti=-1, *, file=None)
+.. function:: disassemble(code, lasti=-1, *, file=None, show_caches=False)
+              disco(code, lasti=-1, *, file=None, show_caches=False)
 
    Disassemble a code object, indicating the last instruction if *lasti* was
    provided.  The output is divided in the following columns:
@@ -220,8 +235,11 @@ operation is being performed, so the intermediate analysis object isn't useful:
    .. versionchanged:: 3.4
       Added *file* parameter.
 
+   .. versionchanged:: 3.11
+      Added the ``show_caches`` parameter.
+
 
-.. function:: get_instructions(x, *, first_line=None)
+.. function:: get_instructions(x, *, first_line=None, show_caches=False)
 
    Return an iterator over the instructions in the supplied function, method,
    source code string or code object.
@@ -236,6 +254,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
 
    .. versionadded:: 3.4
 
+   .. versionchanged:: 3.11
+      Added the ``show_caches`` parameter.
+
 
 .. function:: findlinestarts(code)