8000 bpo-39245: Make Vectorcall public by encukou · Pull Request #17893 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

bpo-39245: Make Vectorcall public #17893

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Feb 6, 2020
Merged

bpo-39245: Make Vectorcall public #17893

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
368ed59
Remove leading underscores from provisional call/Vectorcall API
encukou Nov 26, 2019
116d0d0
Fix up formatting in docs
encukou Nov 26, 2019
f0c005f
Add backcompat defines and move non-limited API declaration to cpython/
encukou Nov 19, 2019
d948983
Adjust documentation
encukou Nov 26, 2019
5e340bf
Add a NEWS entry
encukou Jan 7, 2020
60a8833
Put PyObject_CallNoArgs back in the limited API
encukou Jan 8, 2020
29a8331
Revert "update usage of the renamed functions"
encukou Jan 30, 2020
1f7c746
Rename PyObject_FastCallDict to PyObject_VectorcallDict
encukou Jan 30, 2020
3fc5442
Expand the NEWS entry
encukou Jan 30, 2020
9fff79b
Remove underscores from comments
encukou Feb 4, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 51 additions & 38 deletions Doc/c-api/call.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,17 +35,11 @@ To call an object, use :c:func:`PyObject_Call` or other
The Vectorcall Protocol
-----------------------

.. versionadded:: 3.8
.. versionadded:: 3.9

The vectorcall protocol was introduced in :pep:`590` as an additional protocol
for making calls more efficient.

.. warning::

The vectorcall API is provisional and expected to become public in
Python 3.9, with a different names and, possibly, changed semantics.
If you use the it, plan for updating your code for Python 3.9.

As rule of thumb, CPython will prefer the vectorcall for internal calls
if the callable supports it. However, this is not a hard rule.
Additionally, some third-party extensions use *tp_call* directly
Expand All @@ -69,7 +63,7 @@ the arguments to an args tuple and kwargs dict anyway, then there is no point
in implementing vectorcall.

Classes can implement the vectorcall protocol by enabling the
:const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
:const:`Py_TPFLAGS_HAVE_VECTORCALL` flag and setting
:c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the
object structure where a *vectorcallfunc* appears.
This is a pointer to a function with the following signature:
Expand Down Expand Up @@ -97,7 +91,7 @@ This is a pointer to a function with the following signature:
argument 1 (not 0) in the allocated vector.
The callee must restore the value of ``args[-1]`` before returning.

For :c:func:`_PyObject_VectorcallMethod`, this flag means instead that
For :c:func:`PyObject_VectorcallMethod`, this flag means instead that
``args[0]`` may be changed.

Whenever they can do so cheaply (without additional allocation), callers
Expand All @@ -107,7 +101,20 @@ This is a pointer to a function with the following signature:

To call an object that implements vectorcall, use a :ref:`call API <capi-call>`
function as with any other callable.
:c:func:`_PyObject_Vectorcall` will usually be most efficient.
:c:func:`PyObject_Vectorcall` will usually be most efficient.


.. note::

In CPython 3.8, the vectorcall API and related functions were available
provisionally under names with a leading underscore:
``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``,
``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``,
``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``,
``_PyObject_CallMethodOneArg``.
Additionally, ``PyObject_VectorcallDict`` was available as
``_PyObject_FastCallDict``.
The old names are still defined as aliases of the new, non-underscored names.


Recursion Control
Expand Down Expand Up @@ -137,17 +144,21 @@ Vectorcall Support API
However, the function ``PyVectorcall_NARGS`` should be used to allow
for future extensions.

This function is not part of the `limited API <stable>`_.

.. versionadded:: 3.8

.. c:function:: vectorcallfunc _PyVectorcall_Function(PyObject *op)
.. c:function:: vectorcallfunc PyVectorcall_Function(PyObject *op)

If *op* does not support the vectorcall protocol (either because the type
does not or because the specific instance does not), return *NULL*.
Otherwise, return the vectorcall function pointer stored in *op*.
This function never raises an exception.

This is mostly useful to check whether or not *op* supports vectorcall,
which can be done by checking ``_PyVectorcall_Function(op) != NULL``.
which can be done by checking ``PyVectorcall_Function(op) != NULL``.

This function is not part of the `limited API <stable>`_.

.. versionadded:: 3.8

Expand All @@ -158,9 +169,11 @@ Vectorcall Support API

This is a specialized function, intended to be put in the
:c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
It does not check the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag
It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
and it does not fall back to ``tp_call``.

This function is not part of the `limited API <stable>`_.

.. versionadded:: 3.8


Expand All @@ -185,7 +198,7 @@ please see individual documentation for details.
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallNoArgs` | ``PyObject *`` | --- | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- |
| :c:func:`PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallObject` | ``PyObject *`` | tuple/``NULL`` | --- |
+------------------------------------------+------------------+--------------------+---------------+
Expand All @@ -197,15 +210,15 @@ please see individual documentation for details.
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`PyObject_CallMethodObjArgs` | obj + name | variadic | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_CallMethodNoArgs` | obj + name | --- | --- |
| :c:func:`PyObject_CallMethodNoArgs` | obj + name | --- | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_CallMethodOneArg` | obj + name | 1 object | --- |
| :c:func:`PyObject_CallMethodOneArg` | obj + name | 1 object | --- |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall |
| :c:func:`PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_FastCallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` |
| :c:func:`PyObject_VectorcallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` |
+------------------------------------------+------------------+--------------------+---------------+
| :c:func:`_PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall |
| :c:func:`PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall |
+------------------------------------------+------------------+--------------------+---------------+


Expand Down Expand Up @@ -235,14 +248,16 @@ please see individual documentation for details.
.. versionadded:: 3.9


.. c:function:: PyObject* _PyObject_CallOneArg(PyObject *callable, PyObject *arg)
.. c:function:: PyObject* PyObject_CallOneArg(PyObject *callable, PyObject *arg)

Call a callable Python object *callable* with exactly 1 positional argument
*arg* and no keyword arguments.

Return the result of the call on success, or raise an exception and return
*NULL* on failure.

This function is not part of the `limited API <stable>`_.

.. versionadded:: 3.9


Expand Down Expand Up @@ -320,18 +335,20 @@ please see individual documentation for details.
*NULL* on failure.


.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
.. c:function:: PyObject* PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)

Call a method of the Python object *obj* without arguments,
where the name of the method is given as a Python string object in *name*.

Return the result of the call on success, or raise an exception and return
*NULL* on failure.

This function is not part of the `limited API <stable>`_.

.. versionadded:: 3.9


.. c:function:: PyObject* _PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
.. c:function:: PyObject* PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)

Call a method of the Python object *obj* with a single positional argument
*arg*, where the name of the method is given as a Python string object in
Expand All @@ -340,10 +357,12 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.

This function is not part of the `limited API <stable>`_.

.. versionadded:: 3.9


.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
.. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)

Call a callable Python object *callable*.
The arguments are the same as for :c:type:`vectorcallfunc`.
Expand All @@ -353,15 +372,11 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.

.. 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.
This function is not part of the `limited API <stable>`_.

.. versionadded:: 3.8
.. versionadded:: 3.9

.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
.. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol,
but with keyword arguments passed as a dictionary *kwdict*.
Expand All @@ -373,15 +388,11 @@ please see individual documentation for details.
already has a dictionary ready to use for the keyword arguments,
but not a tuple for the positional arguments.

.. note::
This function is not part of the `limited API <stable>`_.

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
.. versionadded:: 3.9

.. c:function:: PyObject* _PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
.. c:function:: PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)

Call a method using the vectorcall calling convention. The name of the method
is given as a Python string *name*. The object whose method is called is
Expand All @@ -390,7 +401,7 @@ please see individual documentation for details.
*nargsf* is the number of positional arguments including *args[0]*,
plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
temporarily be changed. Keyword arguments can be passed just like in
:c:func:`_PyObject_Vectorcall`.
:c:func:`PyObject_Vectorcall`.

If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
this will call the unbound method object with the full
Expand All @@ -399,6 +410,8 @@ please see individual documentation for details.
Return the result of the call on success, or raise an exception and return
*NULL* on failure.

This function is not part of the `limited API <stable>`_.

.. versionadded:: 3.9


Expand Down
20 changes: 7 additions & 13 deletions Doc/c-api/typeobj.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -693,15 +693,15 @@ and :c:type:`PyType_Type` effectively act as defaults.)
a more efficient alternative
of the simpler :c:member:`~PyTypeObject.tp_call`.

This field is only used if the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL`
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 of a :c:type:`vectorcallfunc` pointer.

The *vectorcallfunc* pointer may be ``NULL``, in which case the instance behaves
as if :const:`_Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
as if :const:`Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
falls back to :c:member:`~PyTypeObject.tp_call`.

Any class that sets ``_Py_TPFLAGS_HAVE_VECTORCALL`` must also set
Any class that sets ``Py_TPFLAGS_HAVE_VECTORCALL`` must also set
:c:member:`~PyTypeObject.tp_call` and make sure its behaviour is consistent
with the *vectorcallfunc* function.
This can be done by setting *tp_call* to :c:func:`PyVectorcall_Call`.
Expand All @@ -728,7 +728,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
**Inheritance:**

This field is always inherited.
However, the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag is not
However, the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is not
always inherited. If it's not, then the subclass won't use
:ref:`vectorcall <vectorcall>`, except when
:c:func:`PyVectorcall_Call` is explicitly called.
Expand Down Expand Up @@ -1162,7 +1162,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
type structure.


.. data:: _Py_TPFLAGS_HAVE_VECTORCALL
.. data:: Py_TPFLAGS_HAVE_VECTORCALL

This bit is set when the class implements
the :ref:`vectorcall protocol <vectorcall>`.
Expand All @@ -1172,15 +1172,9 @@ and :c:type:`PyType_Type` effectively act as defaults.)

This bit is inherited for *static* subtypes if
:c:member:`~PyTypeObject.tp_call` is also inherited.
`Heap types`_ do not inherit ``_Py_TPFLAGS_HAVE_VECTORCALL``.
`Heap types`_ do not inherit ``Py_TPFLAGS_HAVE_VECTORCALL``.

.. note::

This flag is provisional and expected to become public in Python 3.9,
with a different name and, possibly, changed semantics.
If you use vectorcall, plan for updating your code for Python 3.9.

.. versionadded:: 3.8
.. versionadded:: 3.9


.. c:member:: const char* PyTypeObject.tp_doc
Expand Down
Loading
0