The function pointer type

Calls are made through a function pointer taking the following parameters:

• PyObject*callable:The called object
• PyObject*const*args:A vector of arguments
• size_tnargs:The number of arguments plus the optional flagPY_VECTORCALL_ARGUMENTS_OFFSET(see below)
• PyObject*kwnames:EitherNULLor a tuple with the names of the keyword arguments

This is implemented by the function pointer type: typedefPyObject*(*vectorcallfunc)(PyObject*callable,PyObject*const*args,size_tnargs,PyObject*kwnames);

Changes to thePyTypeObjectstruct

The unused slotprintfunctp_printis replaced withtp_vectorcall_offset.It has the typePy_ssize_t. A newtp_flagsflag is added,_Py_TPFLAGS_HAVE_VECTORCALL, which must be set for any class that uses the vectorcall protocol.

If_Py_TPFLAGS_HAVE_VECTORCALLis set, thentp_vectorcall_offsetmust be a positive integer. It is the offset into the object of the vectorcall function pointer of typevectorcallfunc. This pointer may beNULL,in which case the behavior is the same as if_Py_TPFLAGS_HAVE_VECTORCALLwas not set.

Thetp_printslot is reused as thetp_vectorcall_offsetslot to make it easier for external projects to backport the vectorcall protocol to earlier Python versions. In particular, the Cython project has shown interest in doing that (seehttps://mail.python.org/pipermail/python-dev/2018-June/153927.html).

Descriptor behavior

One additional type flag is specified:Py_TPFLAGS_METHOD_DESCRIPTOR.

Py_TPFLAGS_METHOD_DESCRIPTORshould be set if the callable uses the descriptor protocol to create a bound method-like object. This is used by the interpreter to avoid creating temporary objects when calling methods (see_PyObject_GetMethodand theLOAD_METHOD/CALL_METHODopcodes).

Concretely, ifPy_TPFLAGS_METHOD_DESCRIPTORis set fortype(func),then:

• func.__get__(obj,cls)(*args,**kwds)(withobjnot None) must be equivalent tofunc(obj,*args,**kwds).
• func.__get__(None,cls)(*args,**kwds)must be equivalent tofunc(*args,**kwds).

There are no restrictions on the objectfunc.__get__(obj,cls). The latter is not required to implement the vectorcall protocol.

The call

The call takes the form((vectorcallfunc)(((char*)o)+offset))(o,args,n,kwnames)where offsetisPy_TYPE(o)->tp_vectorcall_offset. The caller is responsible for creating thekwnamestuple and ensuring that there are no duplicates in it.

nis the number of positional arguments plus possibly thePY_VECTORCALL_ARGUMENTS_OFFSETflag.

PY_VECTORCALL_ARGUMENTS_OFFSET

The flagPY_VECTORCALL_ARGUMENTS_OFFSETshould be added ton if the callee is allowed to temporarily changeargs[-1]. In other words, this can be used ifargspoints to argument 1 in the allocated vector. The callee must restore the value ofargs[-1]before returning.

Whenever they can do so cheaply (without allocation), callers are encouraged to usePY_VECTORCALL_ARGUMENTS_OFFSET. Doing so will allow callables such as bound methods to make their onward calls cheaply. The bytecode interpreter already allocates space on the stack for the callable, so it can use this trick at no additional cost.

See[3]for an example of howPY_VECTORCALL_ARGUMENTS_OFFSETis used by a callee to avoid allocation.

For getting the actual number of arguments from the parametern, the macroPyVectorcall_NARGS(n)must be used. This allows for future changes or extensions.

Subclassing

Extension types inherit the type flag_Py_TPFLAGS_HAVE_VECTORCALL and the valuetp_vectorcall_offsetfrom the base class, provided that they implementtp_callthe same way as the base class. Additionally, the flagPy_TPFLAGS_METHOD_DESCRIPTOR is inherited iftp_descr_getis implemented the same way as the base class.

Heap types never inherit the vectorcall protocol because that would not be safe (heap types can be changed dynamically). This restriction may be lifted in the future, but that would require special-casing__call__intype.__setattribute__.

Changes to existing classes

Thefunction,builtin_function_or_method,method_descriptor,method,wrapper_descriptor,method-wrapper classes will use the vectorcall protocol (not all of these will be changed in the initial implementation).

Forbuiltin_function_or_methodandmethod_descriptor (which use thePyMethodDefdata structure), one could implement a specific vectorcall wrapper for every existing calling convention. Whether or not it is worth doing that remains to be seen.

Using the vectorcall protocol for classes

For a classcls,creating a new instance usingcls(xxx) requires multiple calls. At least one intermediate object is created for each call in the sequence type.__call__,cls.__new__,cls.__init__. So it makes a lot of sense to use vectorcall for calling classes. This really means implementing the vectorcall protocol fortype. Some of the most commonly used classes will use this protocol, probablyrange,list,str,andtype.

ThePyMethodDefprotocol and Argument Clinic

Argument Clinic[4]automatically generates wrapper functions around lower-level callables, providing safe unboxing of primitive types and other safety checks. Argument Clinic could be extended to generate wrapper objects conforming to the newvectorcallprotocol. This will allow execution to flow from the caller to the Argument Clinic generated wrapper and thence to the hand-written code with only a single indirection.

bpo-29259

PEP 590is close to what was proposed in bpo-29259[1]. The main difference is that this PEP stores the function pointer in the instance rather than in the class. This makes more sense for implementing functions in C, where every instance corresponds to a different C function. It also allows optimizingtype.__call__,which is not possible with bpo-29259.

PEP 576 and PEP 580

BothPEP 576andPEP 580are designed to enable 3rd party objects to be both expressive and performant (on a par with CPython objects). The purpose of this PEP is provide a uniform way to call objects in the CPython ecosystem that is both expressive and as performant as possible.

This PEP is broader in scope thanPEP 576and uses variable rather than fixed offset function-pointers. The underlying calling convention is similar. BecausePEP 576only allows a fixed offset for the function pointer, it would not allow the improvements to any objects with constraints on their layout.

PEP 580proposes a major change to thePyMethodDefprotocol used to define builtin functions. This PEP provides a more general and simpler mechanism in the form of a new calling convention. This PEP also extends thePyMethodDefprotocol, but merely to formalise existing conventions.

Other rejected approaches

A longer, 6 argument, form combining both the vector and optional tuple and dictionary arguments was considered. However, it was found that the code to convert between it and the oldtp_callform was overly cumbersome and inefficient. Also, since only 4 arguments are passed in registers on x64 Windows, the two extra arguments would have non-negligible costs.

Removing any special cases and making all calls use thetp_callform was also considered. However, unless a much more efficient way was found to create and destroy tuples, and to a lesser extent dictionaries, then it would be too slow.