bpo-36974: document PEP 590 (GH-13450)

Author: jdemeyer

Doc/c-api/object.rst

@@ -335,6 +335,83 @@ 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*, using
+   :c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>` if possible.
+
+   *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` (see below).
+   To get actual number of arguments, use
+   :c:func:`PyVectorcall_NARGS(nargsf) <PyVectorcall_NARGS>`.
+
+   *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.
+   The number of keyword arguments does not influence *nargsf*.
+
+   *kwnames* must contain 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 and, possibly, changed semantics.
+      If you use the function, plan for updating your code for Python 3.9.
+
+   .. versionadded:: 3.8
+
+.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET
+
+   If set in a vectorcall *nargsf* argument, the callee is allowed to
+   temporarily change ``args[-1]``. In other words, *args* points to
+   argument 1 (not 0) in the allocated vector.
+   The callee must restore the value of ``args[-1]`` before returning.
+
+   Whenever they can do so cheaply (without additional allocation), callers
+   are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`.
+   Doing so will allow callables such as bound methods to make their onward
+   calls (which include a prepended *self* argument) cheaply.
+
+   .. versionadded:: 3.8
+
+.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf)
+
+   Given a vectorcall *nargsf* argument, return the actual number of
+   arguments.
+   Currently equivalent to ``nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET``.
+
+   .. versionadded:: 3.8
+
+.. 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 :c:data:`vectorcall <PyTypeObject.tp_vectorcall_offset>`,
+   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 and, possibly, changed semantics.
+      If you use the function, plan for updating your code for Python 3.9.
+
+   .. versionadded:: 3.8
+
+
 .. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
 
    .. index:: builtin: hash