8000 bpo-39245: Make Vectorcall C API public (GH-17893) · python/cpython@3f563ce · GitHub
[go: up one dir, main page]
Skip to content

Commit 3f563ce

Browse files
encukouencukou
authored
bpo-39245: Make Vectorcall C API public (GH-17893)
* Add backcompat defines and move non-limited API declaration to cpython/ This partially reverts commit 2ff58a2 which added PyObject_CallNoArgs to the 3.9+ stable ABI. This should not be done; there are enough other call APIs in the stable ABI to choose from. * Adjust documentation Mark all newly public functions as added in 3.9. Add a note about the 3.8 provisional names. Add notes on public API. * Put PyObject_CallNoArgs back in the limited API * Rename PyObject_FastCallDict to PyObject_VectorcallDict
1 parent d2f9667 commit 3f563ce

File tree

5 files changed

+89
-66
lines changed

5 files changed

+89
-66
lines changed

‎Doc/c-api/call.rst

Lines changed: 51 additions & 38 deletions
< 10000 tr class="diff-line-row">
Original file line numberDiff line numberDiff line change
@@ -35,17 +35,11 @@ To call an object, use :c:func:`PyObject_Call` or other
3535
The Vectorcall Protocol
3636
-----------------------
3737

38-
.. versionadded:: 3.8
38+
.. versionadded:: 3.9
3939

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

43-
.. warning::
44-
45-
The vectorcall API is provisional and expected to become public in
46-
Python 3.9, with a different names and, possibly, changed semantics.
47-
If you use the it, plan for updating your code for Python 3.9.
48-
4943
As rule of thumb, CPython will prefer the vectorcall for internal calls
5044
if the callable supports it. However, this is not a hard rule.
5145
Additionally, some third-party extensions use *tp_call* directly
@@ -69,7 +63,7 @@ the arguments to an args tuple and kwargs dict anyway, then there is no point
6963
in implementing vectorcall.
7064

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

100-
For :c:func:`_PyObject_VectorcallMethod`, this flag means instead that
94+
For :c:func:`PyObject_VectorcallMethod`, this flag means instead that
10195
``args[0]`` may be changed.
10296

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

108102
To call an object that implements vectorcall, use a :ref:`call API <capi-call>`
109103
function as with any other callable.
110-
:c:func:`_PyObject_Vectorcall` will usually be most efficient.
104+
:c:func:`PyObject_Vectorcall` will usually be most efficient.
105+
106+
107+
.. note::
108+
109+
In CPython 3.8, the vectorcall API and related functions were available
110+
provisionally under names with a leading underscore:
111+
``_PyObject_Vectorcall``, ``_Py_TPFLAGS_HAVE_VECTORCALL``,
112+
``_PyObject_VectorcallMethod``, ``_PyVectorcall_Function``,
113+
``_PyObject_CallOneArg``, ``_PyObject_CallMethodNoArgs``,
114+
``_PyObject_CallMethodOneArg``.
115+
Additionally, ``PyObject_VectorcallDict`` was available as
116+
``_PyObject_FastCallDict``.
117+
The old names are still defined as aliases of the new, non-underscored names.
111118

112119

113120
Recursion Control
@@ -137,17 +144,21 @@ Vectorcall Support API
137144
However, the function ``PyVectorcall_NARGS`` should be used to allow
138145
for future extensions.
139146
147+
This function is not part of the `limited API <stable>`_.
148+
140149
.. versionadded:: 3.8
141150
142-
.. c:function:: vectorcallfunc _PyVectorcall_Function(PyObject *op)
151+
.. c:function:: vectorcallfunc PyVectorcall_Function(PyObject *op)
143152
144153
If *op* does not support the vectorcall protocol (either because the type
145154
does not or because the specific instance does not), return *NULL*.
146155
Otherwise, return the vectorcall function pointer stored in *op*.
147156
This function never raises an exception.
148157
149158
This is mostly useful to check whether or not *op* supports vectorcall,
150-
which can be done by checking ``_PyVectorcall_Function(op) != NULL``.
159+
which can be done by checking ``PyVectorcall_Function(op) != NULL``.
160+
161+
This function is not part of the `limited API <stable>`_.
151162
152163
.. versionadded:: 3.8
153164
@@ -158,9 +169,11 @@ Vectorcall Support API
158169
159170
This is a specialized function, intended to be put in the
160171
:c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``.
161-
It does not check the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag
172+
It does not check the :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag
162173
and it does not fall back to ``tp_call``.
163174
175+
This function is not part of the `limited API <stable>`_.
176+
164177
.. versionadded:: 3.8
165178
166179
@@ -185,7 +198,7 @@ please see individual documentation for details.
185198
+------------------------------------------+------------------+--------------------+---------------+
186199
| :c:func:`PyObject_CallNoArgs` | ``PyObject *`` | --- | --- |
187200
+------------------------------------------+------------------+--------------------+---------------+
188-
| :c:func:`_PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- |
201+
| :c:func:`PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- |
189202
+------------------------------------------+------------------+--------------------+---------------+
190203
| :c:func:`PyObject_CallObject` | ``PyObject *`` | tuple/``NULL`` | --- |
191204
+------------------------------------------+------------------+--------------------+---------------+
@@ -197,15 +210,15 @@ please see individual documentation for details.
197210
+------------------------------------------+------------------+--------------------+---------------+
198211
| :c:func:`PyObject_CallMethodObjArgs` | obj + name | variadic | --- |
199212
+------------------------------------------+------------------+--------------------+---------------+
200-
| :c:func:`_PyObject_CallMethodNoArgs` | obj + name | --- | --- |
213+
| :c:func:`PyObject_CallMethodNoArgs` | obj + name | --- | --- |
201214
+------------------------------------------+------------------+--------------------+---------------+
202-
| :c:func:`_PyObject_CallMethodOneArg` | obj + name | 1 object | --- |
215+
| :c:func:`PyObject_CallMethodOneArg` | obj + name | 1 object | --- |
203216
+------------------------------------------+------------------+--------------------+---------------+
204-
| :c:func:`_PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall |
217+
| :c:func:`PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall |
205218
+------------------------------------------+------------------+--------------------+---------------+
206-
| :c:func:`_PyObject_FastCallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` |
219+
| :c:func:`PyObject_VectorcallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` |
207220
+------------------------------------------+------------------+--------------------+---------------+
208-
| :c:func:`_PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall |
221+
| :c:func:`PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall |
209222
+------------------------------------------+------------------+--------------------+---------------+
210223
211224
@@ -235,14 +248,16 @@ please see individual documentation for details.
235248
.. versionadded:: 3.9
236249
237250
238-
.. c:function:: PyObject* _PyObject_CallOneArg(PyObject *callable, PyObject *arg)
251+
.. c:function:: PyObject* PyObject_CallOneArg(PyObject *callable, PyObject *arg)
239252
240253
Call a callable Python object *callable* with exactly 1 positional argument
241254
*arg* and no keyword arguments.
242255
243256
Return the result of the call on success, or raise an exception and return
244257
*NULL* on failure.
245258
259+
This function is not part of the `limited API <stable>`_.
260+
246261
.. versionadded:: 3.9
247262
248263
@@ -320,18 +335,20 @@ please see individual documentation for details.
320335
*NULL* on failure.
321336
322337
323-
.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
338+
.. c:function:: PyObject* PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)
324339
325340
Call a method of the Python object *obj* without arguments,
326341
where the name of the method is given as a Python string object in *name*.
327342
328343
Return the result of the call on success, or raise an exception and return
329344
*NULL* on failure.
330345
346+
This function is not part of the `limited API <stable>`_.
347+
331348
.. versionadded:: 3.9
332349
333350
334-
.. c:function:: PyObject* _PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
351+
.. c:function:: PyObject* PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)
335352
336353
Call a method of the Python object *obj* with a single positional argument
337354
*arg*, where the name of the method is given as a Python string object in
@@ -340,10 +357,12 @@ please see individual documentation for details.
340357
Return the result of the call on success, or raise an exception and return
341358
*NULL* on failure.
342359
360+
This function is not part of the `limited API <stable>`_.
361+
343362
.. versionadded:: 3.9
344363
345364
346-
.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
365+
.. c:function:: PyObject* PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
347366
348367
Call a callable Python object *callable*.
349368
The arguments are the same as for :c:type:`vectorcallfunc`.
@@ -353,15 +372,11 @@ please see individual documentation for details.
353372
Return the result of the call on success, or raise an exception and return
354373
*NULL* on failure.
355374
356-
.. note::
357-
358-
This function is provisional and expected to become public in Python 3.9,
359-
with a different name and, possibly, changed semantics.
360-
If you use the function, plan for updating your code for Python 3.9.
375+
This function is not part of the `limited API <stable>`_.
361376
362-
.. versionadded:: 3.8
377+
.. versionadded:: 3.9
363378
364-
.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
379+
.. c:function:: PyObject* PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)
365380
366381
Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol,
367382
but with keyword arguments passed as a dictionary *kwdict*.
@@ -373,15 +388,11 @@ please see individual documentation for details.
373388
already has a dictionary ready to use for the keyword arguments,
374389
but not a tuple for the positional arguments.
375390
376-
.. note::
391+
This function is not part of the `limited API <stable>`_.
377392
378-
This function is provisional and expected to become public in Python 3.9,
379-
with a different name and, possibly, changed semantics.
380-
If you use the function, plan for updating your code for Python 3.9.
381-
382-
.. versionadded:: 3.8
393+
.. versionadded:: 3.9
383394
384-
.. c:function:: PyObject* _PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
395+
.. c:function:: PyObject* PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
385396
386397
Call a method using the vectorcall calling convention. The name of the method
387398
is given as a Python string *name*. The object whose method is called is
@@ -390,7 +401,7 @@ please see individual documentation for details.
390401
*nargsf* is the number of positional arguments including *args[0]*,
391402
plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may
392403
temporarily be changed. Keyword arguments can be passed just like in
393-
:c:func:`_PyObject_Vectorcall`.
404+
:c:func:`PyObject_Vectorcall`.
394405
395406
If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature,
396407
this will call the unbound method object with the full
@@ -399,6 +410,8 @@ please see individual documentation for details.
399410
Return the result of the call on success, or raise an exception and return
400411
*NULL* on failure.
401412
413+
This function is not part of the `limited API <stable>`_.
414+
402415
.. versionadded:: 3.9
403416
404417

‎Doc/c-api/typeobj.rst

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -684,15 +684,15 @@ and :c:type:`PyType_Type` effectively act as defaults.)
684684
a more efficient alternative
685685
of the simpler :c:member:`~PyTypeObject.tp_call`.
686686

687-
This field is only used if the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL`
687+
This field is only used if the flag :const:`Py_TPFLAGS_HAVE_VECTORCALL`
688688
is set. If so, this must be a positive integer containing the offset in the
689689
instance of a :c:type:`vectorcallfunc` pointer.
690690

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

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

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

11551155

1156-
.. data:: _Py_TPFLAGS_HAVE_VECTORCALL
1156+
.. data:: Py_TPFLAGS_HAVE_VECTORCALL
11571157

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

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

1168-
.. note::
1169-
1170-
This flag is provisional and expected to become public in Python 3.9,
1171-
with a different name and, possibly, changed semantics.
1172-
If you use vectorcall, plan for updating your code for Python 3.9.
1173-
1174-
.. versionadded:: 3.8
1168+
.. versionadded:: 3.9
11751169

11761170

11771171
.. c:member:: const char* PyTypeObject.tp_doc

0 commit comments

Comments
 (0)
0