8000 gh-100554: Add ``Py_tp_vectorcall`` slot to set ``PyTypeObject.tp_vec… · python/cpython@74330d9 · GitHub
[go: up one dir, main page]
Skip to content

Commit 74330d9

Browse files
wjakobwjakob
authored
gh-100554: Add Py_tp_vectorcall slot to set PyTypeObject.tp_vectorcall using the PyType_FromSpec function family. (#123332)
1 parent bbb36c0 commit 74330d9

File tree

8 files changed

+147
-10
lines changed

8 files changed

+147
-10
lines changed

‎Doc/c-api/type.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -504,11 +504,8 @@ The following functions and structs are used to create
504504
See :ref:`PyMemberDef documentation <pymemberdef-offsets>`
505505
for details.
506506
507-
The following fields cannot be set at all when creating a heap type:
508-
509-
* :c:member:`~PyTypeObject.tp_vectorcall`
510-
(use :c:member:`~PyTypeObject.tp_new` and/or
511-
:c:member:`~PyTypeObject.tp_init`)
507+
The following internal fields cannot be set at all when creating a heap
508+
type:
512509
513510
* Internal fields:
514511
:c:member:`~PyTypeObject.tp_dict`,
@@ -531,6 +528,12 @@ The following functions and structs are used to create
531528
:c:member:`~PyBufferProcs.bf_releasebuffer` are now available
532529
under the :ref:`limited API <limited-c-api>`.
533530
531+
.. versionchanged:: 3.14
532+
533+
The field :c:member:`~PyTypeObject.tp_vectorcall` can now set
534+
using ``Py_tp_vectorcall``. See the field's documentation
535+
for details.
536+
534537
.. c:member:: void *pfunc
535538
536539
The desired value of the slot. In most cases, this is a pointer

‎Doc/c-api/typeobj.rst

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2137,11 +2137,40 @@ and :c:data:`PyType_Type` effectively act as defaults.)
21372137

21382138
.. c:member:: vectorcallfunc PyTypeObject.tp_vectorcall
21392139
2140-
Vectorcall function to use for calls of this type object.
2141-
In other words, it is used to implement
2142-
:ref:`vectorcall <vectorcall>` for ``type.__call__``.
2143-
If ``tp_vectorcall`` is ``NULL``, the default call implementation
2144-
using :meth:`~object.__new__` and :meth:`~object.__init__` is used.
2140+
A :ref:`vectorcall function <vectorcall>` to use for calls of this type
2141+
object (rather than instances).
2142+
In other words, ``tp_vectorcall`` can be used to optimize ``type.__call__``,
2143+
which typically returns a new instance of *type*.
2144+
2145+
As with any vectorcall function, if ``tp_vectorcall`` is ``NULL``,
2146+
the *tp_call* protocol (``Py_TYPE(type)->tp_call``) is used instead.
2147+
2148+
.. note::
2149+
2150+
The :ref:`vectorcall protocol <vectorcall>` requires that the vectorcall
2151+
function has the same behavior as the corresponding ``tp_call``.
2152+
This means that ``type->tp_vectorcall`` must match the behavior of
2153+
``Py_TYPE(type)->tp_call``.
2154+
2155+
Specifically, if *type* uses the default metaclass,
2156+
``type->tp_vectorcall`` must behave the same as
2157+
:c:expr:`PyType_Type->tp_call`, which:
2158+
2159+
- calls ``type->tp_new``,
2160+
2161+
- if the result is a subclass of *type*, calls ``type->tp_init``
2162+
on the result of ``tp_new``, and
2163+
2164+
- returns the result of ``tp_new``.
2165+
2166+
Typically, ``tp_vectorcall`` is overridden to optimize this process
2167+
for specific :c:member:`~PyTypeObject.tp_new` and
2168+
:c:member:`~PyTypeObject.tp_init`.
2169+
When doing this for user-subclassable types, note that both can be
2170+
overridden (using :py:func:`~object.__new__` and
2171+
:py:func:`< F438 span class="pl-s">~object.__init__`, respectively).
2172+
2173+
21452174

21462175
**Inheritance:**
21472176

‎Include/typeslots.h

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,3 +86,7 @@
8686
/* New in 3.10 */
8787
#define Py_am_send 81
8888
#endif
89+
#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030E0000
90+
/* New in 3.14 */
91+
#define Py_tp_vectorcall 82
92+
#endif

‎Lib/test/test_capi/test_misc.py

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -733,6 +733,14 @@ class Base(metaclass=metaclass):
733733
with self.assertRaisesRegex(TypeError, msg):
734734
sub = _testcapi.make_type_with_base(Base)
735735

736+
def test_heaptype_with_tp_vectorcall(self):
737+
tp = _testcapi.HeapCTypeVectorcall
738+
v0 = tp.__new__(tp)
739+
v0.__init__()
740+
v1 = tp()
741+
self.assertEqual(v0.value, 2)
742+
self.assertEqual(v1.value, 1)
743+
736744
def test_multiple_inheritance_ctypes_with_weakref_or_dict(self):
737745
for weakref_cls in (_testcapi.HeapCTypeWithWeakref,
738746
_testlimitedcapi.HeapCTypeWithRelativeWeakref):

‎Misc/NEWS.d/next/C_API/2024-08-26-13-01-20.gh-issue-100554.0ku85o.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Added a slot ``Py_tp_vectorcall`` to set
2+
:c:member:`~PyTypeObject.tp_vectorcall` via the :c:func:`PyType_FromSpec`
3+
function family. Limited API extensions can use this feature to provide more
4+
efficient vector call-based implementation of ``__new__`` and ``__init__``.

‎Misc/stable_abi.toml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2526,3 +2526,5 @@
25262526
added = '3.14'
25272527
[function.PyLong_AsUInt64]
25282528
added = '3.14'
2529+
[const.Py_tp_vectorcall]
2530+
added = '3.14'

‎Modules/_testcapi/heaptype.c

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1008,6 +1008,89 @@ static PyType_Spec HeapCTypeSetattr_spec = {
10081008
HeapCTypeSetattr_slots
10091009
};
10101010

1011+
/*
1012+
* The code below is for a test that uses PyType_FromSpec API to create a heap
1013+
* type that simultaneously exposes
1014+
*
1015+
* - A regular __new__ / __init__ constructor pair
1016+
* - A vector call handler in the type object
1017+
*
1018+
* A general requirement of vector call implementations is that they should
1019+
* behave identically (except being potentially faster). The example below
1020+
* deviates from this rule by initializing the instance with a different value.
1021+
* This is only done here only so that we can see which path was taken and is
1022+
* strongly discouraged in other cases.
1023+
*/
1024+
1025+
typedef struct {
1026+
PyObject_HEAD
1027+
long value;
1028+
} HeapCTypeVectorcallObject;
1029+
1030+
static PyObject *heapctype_vectorcall_vectorcall(PyObject *self,
1031+
PyObject *const *args_in,
1032+
size_t nargsf,
1033+
10000 PyObject *kwargs_in)
1034+
{
1035+
if (kwargs_in || PyVectorcall_NARGS(nargsf)) {
1036+
return PyErr_Format(PyExc_IndexError, "HeapCTypeVectorcall() takes no arguments!");
1037+
}
1038+
1039+
HeapCTypeVectorcallObject *r =
1040+
PyObject_New(HeapCTypeVectorcallObject, (PyTypeObject *) self);
1041+
1042+
if (!r) {
1043+
return NULL;
1044+
}
1045+
1046+
r->value = 1;
1047+
1048+
return (PyObject *) r;
1049+
}
1050+
1051+
static PyObject *
1052+
heapctype_vectorcall_new(PyTypeObject* type, PyObject* args, PyObject *kwargs)
1053+
{
1054+
if (PyTuple_GET_SIZE(args) || kwargs) {
1055+
return PyErr_Format(PyExc_IndexError, "HeapCTypeVectorcall() takes no arguments!");
1056+
}
1057+
1058+
return (PyObject *) PyObject_New(HeapCTypeVectorcallObject, type);
1059+
}
1060+
1061+
static int
1062+
heapctype_vectorcall_init(PyObject *self, PyObject *args, PyObject *kwargs) {
1063+
if (PyTuple_GET_SIZE(args) || kwargs) {
1064+
PyErr_Format(PyExc_IndexError, "HeapCTypeVectorcall() takes no arguments!");
1065+
return -1;
1066+
}
1067+
1068+
HeapCTypeVectorcallObject *o = (HeapCTypeVectorcallObject *) self;
1069+
o->value = 2;
1070+
return 0;
1071+
}
1072+
1073+
static struct PyMemberDef heapctype_vectorcall_members[] = {
1074+
{"value", Py_T_LONG, offsetof(HeapCTypeVectorcallObject, value), 0, NULL},
1075+
{NULL}
1076+
};
1077+
1078+
static PyType_Slot HeapCTypeVectorcall_slots[] = {
1079+
{Py_tp_new, heapctype_vectorcall_new},
1080+
{Py_tp_init, heapctype_vectorcall_init},
1081+
{Py_tp_vectorcall, heapctype_vectorcall_vectorcall},
1082+
{Py_tp_members, heapctype_vectorcall_members},
1083+
{0, 0},
1084+
};
1085+
1086+
static PyType_Spec HeapCTypeVectorcall_spec = {
1087+
"_testcapi.HeapCTypeVectorcall",
1088+
sizeof(HeapCTypeVectorcallObject),
1089+
0,
1090+
Py_TPFLAGS_DEFAULT,
1091+
HeapCTypeVectorcall_slots
1092+
};
1093+
10111094
PyDoc_STRVAR(HeapCCollection_doc,
10121095
"Tuple-like heap type that uses PyObject_GetItemData for items.");
10131096

@@ -1180,6 +1263,9 @@ _PyTestCapi_Init_Heaptype(PyObject *m) {
11801263
PyObject *HeapCTypeSetattr = PyType_FromSpec(&HeapCTypeSetattr_spec);
11811264
ADD("HeapCTypeSetattr", HeapCTypeSetattr);
11821265

1266+
PyObject *HeapCTypeVectorcall = PyType_FromSpec(&HeapCTypeVectorcall_spec);
1267+
ADD("HeapCTypeVectorcall", HeapCTypeVectorcall);
1268+
11831269
PyObject *subclass_with_finalizer_bases = PyTuple_Pack(1, HeapCTypeSubclass);
11841270
if (subclass_with_finalizer_bases == NULL) {
11851271
return -1;

‎Objects/typeslots.inc

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)
0