bpo-36974: document PEP 590

encukou · Jun 2, 2019 · May 20, 2019 · May 31, 2019 · May 31, 2019 · May 31, 2019
commit 47c9bc089be9279d278397afe29036db09700b33
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
@@ -335,6 +335,58 @@ Object Protocol
    *NULL* on failure.
 
 
+.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
+
+   Call a callable Python object *callable*.
+
+   *args* is a C array with the positional arguments.
+
+   *nargsf* is the number of positional arguments plus optionally the flag
+   :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` which means that the callee is
+   allowed to modify ``args[-1]``.
+
+   *kwnames* can be either NULL (no keyword arguments) or a tuple of keyword
+   names. In the latter case, the values of the keyword arguments are stored
+   in *args* after the positional arguments
+   (note that the number of keyword arguments does not change *nargsf*).
+
+   *kwnames* must only objects of type ``str`` (not a subclass),
+   and all keys must be unique.
+
+   Return the result of the call on success, or *NULL* on failure.
+
+   This uses the vectorcall protocol if the callable supports it;
+   otherwise, the arguments are converted to use
+   :c:member:`~PyTypeObject.tp_call`.
+
+.. note::
+
+   This function is provisional and expected to become public in Python 3.9,
+   with a different name. If so, the plan is to keep the old name
+   ``_PyObject_Vectorcall`` at least in Python 3.9 for backwards compatibility.
+   It is also possible however that the API will be changed and that
+   this functions will be dropped or replaced by a different function.
+
+.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
+
+   Same as :c:func:`_PyObject_Vectorcall` except that the keyword arguments
+   are passed as a dictionary in *kwdict*. This may be *NULL* if there
+   are no keyword arguments.
+
+   For callables supporting vectorcall, the arguments are internally
+   converted to the vectorcall convention. Therefore, this function
+   adds some overhead compared to :c:func:`_PyObject_Vectorcall`.
+   It should only be used if the caller already has a dictionary ready to use.
+
+.. note::
+
+   This function is provisional and expected to become public in Python 3.9,
+   with a different name. If so, the plan is to keep the old name
+   ``_PyObject_FastCallDict`` at least in Python 3.9 for backwards compatibility.
+   It is also possible however that the API will be changed and that
+   this functions will be dropped or replaced by a different function.
+
+
 .. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
 
    .. index:: builtin: hash

diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
@@ -335,3 +335,11 @@ definition with the same method name.
 
    In case the attribute should be deleted the second parameter is *NULL*.
    Should return ``0`` on success or ``-1`` with a set exception on failure.
+
+
+Vectorcall: implementing fast callables
+---------------------------------------
+
+
+
+.. c:type:: PyObject *(*_vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
@@ -49,7 +49,7 @@ Quick Reference
    +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
    | :c:member:`~PyTypeObject.tp_dealloc`        | :c:type:`destructor`              |                   | X | X |   | X |
    +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
-   | (:c:member:`~PyTypeObject.tp_print`)        |                                                                       |
+   | :c:member:`~PyTypeObject.tp_vectorcall_offset`| Py_ssize_t                      |                   |   |   |   | ? |
    +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
    | (:c:member:`~PyTypeObject.tp_getattr`)      | :c:type:`getattrfunc`             | __getattribute__, |   |   |   | G |
    |                                             |                                   | __getattr__       |   |   |   |   |
@@ -364,12 +364,6 @@ slot typedefs
 +-----------------------------+-----------------------------+----------------------+
 | :c:type:`reprfunc`          | :c:type:`PyObject` *        | :c:type:`PyObject` * |
 +-----------------------------+-----------------------------+----------------------+
-| :c:type:`printfunc`         | .. line-block::             | int                  |
-|                             |                             |                      |
-|                             |    :c:type:`PyObject` *     |                      |
-|                             |    FILE *                   |                      |
-|                             |    int                      |                      |
-+-----------------------------+-----------------------------+----------------------+
 | :c:type:`getattrfunc`       | .. line-block::             | :c:type:`PyObject` * |
 |                             |                             |                      |
 |                             |    :c:type:`PyObject` *     |                      |
@@ -675,9 +669,22 @@ and :c:type:`PyType_Type` effectively act as defaults.)
    This field is inherited by subtypes.
 
 
-.. c:member:: printfunc PyTypeObject.tp_print
+.. c:member:: Py_ssize_t PyTypeObject.tp_vectorcall_offset
+
+   This field is only used if the flag :const:`Py_TPFLAGS_HAVE_VECTORCALL`
+   is set. If so, this must be a positive integer containing the offset in the
+   instance struct of the ``vectorcallfunc`` pointer used for the vectorcall
+   protocol.
 
-   Reserved slot, formerly used for print formatting in Python 2.x.
+   This pointer may be zero, in which case the instance behaves as if
+   :const:`Py_TPFLAGS_HAVE_VECTORCALL` was not set.
+
+   **Inheritance:**
+
+   This field is inherited for extension types
+   together with the flag :const:`Py_TPFLAGS_HAVE_VECTORCALL`,
+   but only if :c:member:`~PyTypeObject.tp_call` is also inherited.
+   Heap types never inherit this.
 
 
 .. c:member:: getattrfunc PyTypeObject.tp_getattr
@@ -2302,10 +2309,6 @@ Slot Type typedefs
 
    See :c:member:`~PyTypeObject.tp_repr`.
 
-.. c:type:: int (*printfunc)(PyObject *, FILE *, int)
-
-   This is hidden if :const:`PY_LIMITED_API` is set.
-
 .. c:type:: PyObject *(*getattrfunc)(PyObject *self, char *attr)
 
    Return the value of the named attribute for the object.
@@ -2409,7 +2412,7 @@ with a more verbose initializer::
        sizeof(MyObject),               /* tp_basicsize */
        0,                              /* tp_itemsize */
        (destructor)myobj_dealloc,      /* tp_dealloc */
-       0,                              /* tp_print */
+       0,                              /* tp_vectorcall_offset */
        0,                              /* tp_getattr */
        0,                              /* tp_setattr */
        0,                              /* tp_as_async */

diff --git a/Doc/includes/typestruct.h b/Doc/includes/typestruct.h
@@ -6,7 +6,7 @@ typedef struct _typeobject {
     /* Methods to implement standard operations */
 
     destructor tp_dealloc;
-    printfunc tp_print;
+    Py_ssize_t tp_vectorcall_offset;
     getattrfunc tp_getattr;
     setattrfunc tp_setattr;
     PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)

diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
@@ -238,6 +238,22 @@ See :pep:`587` for a full description.
 (Contributed by Victor Stinner in :issue:`36763`.)
 
 
+Vectorcall: a fast calling protocol for CPython
+-----------------------------------------------
+
+The "vectorcall" protocol is added to the Python/C API.
+It is meant to formalize existing optimizations which were already done
+for various classes.
+Any extension type implementing callables can use this protocol.
+
+This is currently provisional,
+the aim is to make it fully public in Python 3.9.
+
+See :pep:`590` for a full description.
+
+(Contributed by Jeroen Demeyer and Mark Shannon in :issue:`36974`.)
+
+
 Other Language Changes
 ======================