Commit 9e3e06e5 authored by Jeroen Demeyer's avatar Jeroen Demeyer Committed by Petr Viktorin

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

parent 82eac26a
......@@ -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
......
This diff is collapsed.
......@@ -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)
......
......@@ -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 a callable 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
======================
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment