Merge branch 'main' into Optimize-_CALL_METHOD_DESCRIPTOR_NOARGS

Author: Sacul0457

Doc/c-api/dict.rst

@@ -45,7 +45,7 @@ Dictionary objects
    The first argument can be a :class:`dict`, a :class:`frozendict`, or a
    mapping.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -76,7 +76,7 @@ Dictionary objects
 
    The first argument can be a :class:`dict` or a :class:`frozendict`.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -90,7 +90,7 @@ Dictionary objects
 
    .. versionadded:: 3.13
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -142,7 +142,7 @@ Dictionary objects
 
    .. versionadded:: 3.13
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
    See also the :c:func:`PyObject_GetItem` function.
@@ -166,7 +166,7 @@ Dictionary objects
       Calling this API without an :term:`attached thread state` had been allowed for historical
       reason. It is no longer allowed.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -177,7 +177,7 @@ Dictionary objects
    occurred.  Return ``NULL`` **without** an exception set if the key
    wasn't present.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -195,7 +195,7 @@ Dictionary objects
       Prefer using the :c:func:`PyDict_GetItemWithError` function with your own
       :c:func:`PyUnicode_FromString` *key* instead.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -207,7 +207,7 @@ Dictionary objects
 
    .. versionadded:: 3.13
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -275,7 +275,7 @@ Dictionary objects
 
    The first argument can be a :class:`dict` or a :class:`frozendict`.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -285,7 +285,7 @@ Dictionary objects
 
    The first argument can be a :class:`dict` or a :class:`frozendict`.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -296,7 +296,7 @@ Dictionary objects
 
    The first argument can be a :class:`dict` or a :class:`frozendict`.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -309,15 +309,15 @@ Dictionary objects
 
    The argument can be a :class:`dict` or a :class:`frozendict`.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
 .. c:function:: Py_ssize_t PyDict_GET_SIZE(PyObject *p)
 
    Similar to :c:func:`PyDict_Size`, but without error checking.
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 
@@ -391,7 +391,7 @@ Dictionary objects
       :term:`strong reference <strong reference>` (for example, using
       :c:func:`Py_NewRef`).
 
-   .. versionchanged:: next
+   .. versionchanged:: 3.15
       Also accept :class:`frozendict`.
 
 .. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)

Doc/c-api/gcsupport.rst

@@ -220,54 +220,237 @@ The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter o
    detection; it's not expected that users will need to write their own
    visitor functions.
 
-The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
+The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or ``NULL``
+if the object is immutable.
+
+
+.. c:type:: int (*inquiry)(PyObject *self)
+
+   Drop references that may have created reference cycles.  Immutable objects
+   do not have to define this method since they can never directly create
+   reference cycles.  Note that the object must still be valid after calling
+   this method (don't just call :c:func:`Py_DECREF` on a reference).  The
+   collector will call this method if it detects that this object is involved
+   in a reference cycle.
+
+
+.. _gc-traversal:
 
+Traversal
+---------
+
+The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
 
 .. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
 
-   Traversal function for a container object.  Implementations must call the
+   Traversal function for a garbage-collected object, used by the garbage
+   collector to detect reference cycles.
+   Implementations must call the
    *visit* function for each object directly contained by *self*, with the
    parameters to *visit* being the contained object and the *arg* value passed
    to the handler.  The *visit* function must not be called with a ``NULL``
-   object argument.  If *visit* returns a non-zero value that value should be
+   object argument.  If *visit* returns a non-zero value, that value should be
    returned immediately.
 
-   The traversal function must not have any side effects.  Implementations
-   may not modify the reference counts of any Python objects nor create or
-   destroy any Python objects.
+   A typical :c:member:`!tp_traverse` function calls the :c:func:`Py_VISIT`
+   convenience macro on each of the instance's members that are Python
+   objects that the instance owns.
+   For example, this is a (slightly outdated) traversal function for
+   the :py:class:`threading.local` class::
+
+      static int
+      local_traverse(PyObject *op, visitproc visit, void *arg)
+      {
+          localobject *self = (localobject *) op;
+          Py_VISIT(Py_TYPE(self));
+          Py_VISIT(self->args);
+          Py_VISIT(self->kw);
+          Py_VISIT(self->dict);
+          return 0;
+      }
+
+   .. note::
+      :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to
+      :c:func:`!local_traverse` to have these specific names; don't name them just
+      anything.
+
+   Instances of :ref:`heap-allocated types <heap-types>` hold a reference to
+   their type. Their traversal function must therefore visit the type::
+
+       Py_VISIT(Py_TYPE(self));
+
+   Alternately, the type may delegate this responsibility by
+   calling ``tp_traverse`` of a heap-allocated superclass (or another
+   heap-allocated type, if applicable).
+   If they do not, the type object may not be garbage-collected.
+
+   If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
+   :c:member:`~PyTypeObject.tp_flags` field, the traverse function must call
+   :c:func:`PyObject_VisitManagedDict` like this::
+
+       int err = PyObject_VisitManagedDict((PyObject*)self, visit, arg);
+       if (err) {
+           return err;
+       }
+
+   Only the members that the instance *owns* (by having
+   :term:`strong references <strong reference>` to them) must be
+   visited. For instance, if an object supports weak references via the
+   :c:member:`~PyTypeObject.tp_weaklist` slot, the pointer supporting
+   the linked list (what *tp_weaklist* points to) must **not** be
+   visited as the instance does not directly own the weak references to itself.
+
+   The traversal function has a limitation:
+
+   .. warning::
+
+      The traversal function must not have any side effects.  Implementations
+      may not modify the reference counts of any Python objects nor create or
+      destroy any Python objects, directly or indirectly.
+
+   This means that *most* Python C API functions may not be used, since
+   they can raise a new exception, return a new reference to a result object,
+   have internal logic that uses side effects.
+   Also, unless documented otherwise, functions that happen to not have side
+   effects may start having them in future versions, without warning.
+
+   For a list of safe functions, see a
+   :ref:`separate section <duringgc-functions>` below.
+
+   .. note::
+
+      The :c:func:`Py_VISIT` call may be skipped for those members that provably
+      cannot participate in reference cycles.
+      In the ``local_traverse`` example above, there is also a ``self->key``
+      member, but it can only be ``NULL`` or a Python string and therefore
+      cannot be part of a reference cycle.
+
+      On the other hand, even if you know a member can never be part of a cycle,
+      as a debugging aid you may want to visit it anyway just so the :mod:`gc`
+      module's :func:`~gc.get_referents` function will include it.
+
+   .. note::
+
+      The :c:member:`~PyTypeObject.tp_traverse` function can be called from any
+      thread.
 
-To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
-provided.  In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse` implementation
-must name its arguments exactly *visit* and *arg*:
+      .. impl-detail::
 
+         Garbage collection is a "stop-the-world" operation:
+         even in :term:`free threading` builds, only one thread state is
+         :term:`attached <attached thread state>` when :c:member:`!tp_traverse`
+         handlers run.
+
+   .. versionchanged:: 3.9
+
+      Heap-allocated types are expected to visit ``Py_TYPE(self)`` in
+      ``tp_traverse``.  In earlier versions of Python, due to
+      `bug 40217 <https://bugs.python.org/issue40217>`_, doing this
+      may lead to crashes in subclasses.
+
+To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers,
+a :c:func:`Py_VISIT` macro is provided.
+In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse`
+implementation must name its arguments exactly *visit* and *arg*:
 
 .. c:macro:: Py_VISIT(o)
 
-   If the :c:expr:`PyObject *` *o* is not ``NULL``, call the *visit* callback, with arguments *o*
-   and *arg*.  If *visit* returns a non-zero value, then return it.
-   Using this macro, :c:member:`~PyTypeObject.tp_traverse` handlers
-   look like::
+   If the :c:expr:`PyObject *` *o* is not ``NULL``, call the *visit*
+   callback, with arguments *o* and *arg*.
+   If *visit* returns a non-zero value, then return it.
 
-      static int
-      my_traverse(Noddy *self, visitproc visit, void *arg)
-      {
-          Py_VISIT(self->foo);
-          Py_VISIT(self->bar);
-          return 0;
-      }
+   This corresponds roughly to::
 
-The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or ``NULL``
-if the object is immutable.
+      #define Py_VISIT(o)                             \
+         if (op) {                                    \
+            int visit_result = visit(o, arg);         \
+            if (visit_result != 0) {                  \
+               return visit_result;                   \
+            }                                         \
+         }
 
 
-.. c:type:: int (*inquiry)(PyObject *self)
+Traversal-safe functions
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-   Drop references that may have created reference cycles.  Immutable objects
-   do not have to define this method since they can never directly create
-   reference cycles.  Note that the object must still be valid after calling
-   this method (don't just call :c:func:`Py_DECREF` on a reference).  The
-   collector will call this method if it detects that this object is involved
-   in a reference cycle.
+The following functions and macros are safe to use in a
+:c:member:`~PyTypeObject.tp_traverse` handler:
+
+* the *visit* function passed to ``tp_traverse``
+* :c:func:`Py_VISIT`
+* :c:func:`Py_SIZE`
+* :c:func:`Py_TYPE`: if called from a :c:member:`!tp_traverse` handler,
+  :c:func:`!Py_TYPE`'s result will be valid for the duration of the handler call
+* :c:func:`PyObject_VisitManagedDict`
+* :c:func:`PyObject_TypeCheck`, :c:func:`PyType_IsSubtype`,
+  :c:func:`PyType_HasFeature`
+* :samp:`Py{<type>}_Check` and :samp:`Py{<type>}_CheckExact` -- for example,
+  :c:func:`PyTuple_Check`
+* :ref:`duringgc-functions`
+
+.. _duringgc-functions:
+
+"DuringGC" functions
+^^^^^^^^^^^^^^^^^^^^
+
+The following functions should *only* be used in a
+:c:member:`~PyTypeObject.tp_traverse` handler; calling them in other
+contexts may have unintended consequences.
+
+These functions act like their counterparts without the ``_DuringGC`` suffix,
+but they are guaranteed to not have side effects, they do not set an exception
+on failure, and they return/set :term:`borrowed references <borrowed reference>`
+as detailed in the individual documentation.
+
+Note that these functions may fail (return ``NULL`` or ``-1``),
+but as they do not set an exception, no error information is available.
+In some cases, failure is not distinguishable from a successful ``NULL`` result.
+
+.. c:function:: void *PyObject_GetTypeData_DuringGC(PyObject *o, PyTypeObject *cls)
+                void *PyObject_GetItemData_DuringGC(PyObject *o)
+                void *PyType_GetModuleState_DuringGC(PyTypeObject *type)
+                void *PyModule_GetState_DuringGC(PyObject *module)
+                int PyModule_GetToken_DuringGC(PyObject *module, void** result)
+
+   See :ref:`duringgc-functions` for common information.
+
+   .. versionadded:: next
+
+   .. seealso::
+
+      :c:func:`PyObject_GetTypeData`,
+      :c:func:`PyObject_GetItemData`,
+      :c:func:`PyType_GetModuleState`,
+      :c:func:`PyModule_GetState`,
+      :c:func:`PyModule_GetToken`,
+      :c:func:`PyType_GetBaseByToken`
+
+.. c:function:: int PyType_GetBaseByToken_DuringGC(PyTypeObject *type, void *tp_token, PyTypeObject **result)
+
+   See :ref:`duringgc-functions` for common information.
+
+   Sets *\*result* to a :term:`borrowed reference` rather than a strong one.
+   The reference is valid for the duration
+   of the :c:member:`!tp_traverse` handler call.
+
+   .. versionadded:: next
+
+   .. seealso:: :c:func:`PyType_GetBaseByToken`
+
+.. c:function:: PyObject* PyType_GetModule_DuringGC(PyTypeObject *type)
+                PyObject* PyType_GetModuleByToken_DuringGC(PyTypeObject *type, const void *mod_token)
+
+   See :ref:`duringgc-functions` for common information.
+
+   These functions return a :term:`borrowed reference`, which is
+   valid for the duration of the :c:member:`!tp_traverse` handler call.
+
+   .. versionadded:: next
+
+   .. seealso::
+
+      :c:func:`PyType_GetModule`,
+      :c:func:`PyType_GetModuleByToken`
 
 
 Controlling the Garbage Collector State