Skip to content

Commit 3e5f5b0

Browse files
committed
Reword tp_vectorcall_offset; document PyVectorcall_Call
1 parent 24d79fe commit 3e5f5b0

File tree

1 file changed

+40
-10
lines changed

1 file changed

+40
-10
lines changed

Doc/c-api/typeobj.rst

Lines changed: 40 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -671,20 +671,28 @@ and :c:type:`PyType_Type` effectively act as defaults.)
671671

672672
.. c:member:: Py_ssize_t PyTypeObject.tp_vectorcall_offset
673673
674+
An optional offset to a per-instance function that implements calling
675+
the object using the *vectorcall* protocol, a more efficient alternative
676+
of the simpler :c:member:`~PyTypeObject.tp_call`.
677+
674678
This field is only used if the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL`
675679
is set. If so, this must be a positive integer containing the offset in the
676-
instance struct of the :c:type:`vectorcallfunc` pointer used for the vectorcall
677-
protocol.
680+
instance of a :c:type:`vectorcallfunc` pointer.
681+
Arguments to ``vectorcallfunc`` are the same as for :c:func:`_PyObject_Vectorcall`.
678682

679-
This pointer may be zero, in which case the instance behaves as if
680-
:const:`_Py_TPFLAGS_HAVE_VECTORCALL` was not set.
683+
The *vectorcallfunc* pointer may be zero, in which case the instance behaves
684+
as if :const:`_Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance
685+
falls back to :c:member:`~PyTypeObject.tp_call`.
681686

682-
**Inheritance:**
687+
Any class that sets ``_Py_TPFLAGS_HAVE_VECTORCALL`` must also set
688+
:c:member:`~PyTypeObject.tp_call` and make sure its behaviour is consistent
689+
with the *vectorcallfunc* function. This can be done by setting *tp_call* to
690+
``PyVectorcall_Call``:
683691

684-
This field is inherited for extension types
685-
together with the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL`,
686-
but only if :c:member:`~PyTypeObject.tp_call` is also inherited.
687-
Heap types never inherit this.
692+
.. c:function:: PyObject *PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict)
693+
694+
Call *callable*'s *vectorcallfunc* with positional and keyword
695+
arguments given in a tuple and dict, respectively.
688696
689697
.. note::
690698
@@ -695,7 +703,14 @@ and :c:type:`PyType_Type` effectively act as defaults.)
695703
.. versionchanged:: 3.8
696704
697705
This slot was used for print formatting in Python 2.x.
698-
Up to Python 3.7, it was named ``tp_print``.
706+
In Python 3.0 to 3.7, it was reserved and named ``tp_print``.
707+
708+
**Inheritance:**
709+
710+
This slot is inherited for static extension types
711+
together with the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL`,
712+
but only if :c:member:`~PyTypeObject.tp_call` is also inherited.
713+
`Heap types`_ never inherit this.
699714
700715
701716
.. c:member:: getattrfunc PyTypeObject.tp_getattr
@@ -1122,6 +1137,19 @@ and :c:type:`PyType_Type` effectively act as defaults.)
11221137
:c:member:`~PyTypeObject.tp_finalize` slot is always present in the
11231138
type structure.
11241139

1140+
.. data:: _Py_TPFLAGS_HAVE_VECTORCALL
1141+
1142+
This bit is set when the class implements the vectorcall protocol.
1143+
See :c:member:`~PyTypeObject.tp_vectorcall_offset` for details.
1144+
1145+
.. note::
1146+
1147+
This flag is provisional and expected to become public in Python 3.9,
1148+
with a different name and, possibly, changed semantics.
1149+
If you use vectorcall, plan for updating your code for Python 3.9.
1150+
1151+
.. versionadded:: 3.8
1152+
11251153

11261154
.. c:member:: const char* PyTypeObject.tp_doc
11271155
@@ -2308,6 +2336,8 @@ Slot Type typedefs
23082336
23092337
See :c:member:`~PyTypeObject.tp_vectorcall_offset`.
23102338

2339+
Arguments to ``vectorcallfunc`` are the same as for :c:func:`_PyObject_Vectorcall`.
2340+
23112341
.. versionadded: 3.8
23122342
23132343
.. c:type:: void (*freefunc)(void *)

0 commit comments

Comments
 (0)