gh-139922: Tail calling for MSVC (VS 2026)

.github/workflows/tail-call.yml

@@ -79,19 +79,17 @@ jobs:
  with:
  python-version: '3.11'
 
- - name: Native Windows (debug)
+ - name: Native Windows MSVC (PGO)
  if: runner.os == 'Windows' && matrix.architecture != 'ARM64'
  shell: cmd
  run: |
- choco install llvm --allow-downgrade --no-progress --version ${{ matrix.llvm }}.1.0
- set PlatformToolset=clangcl
- set LLVMToolsVersion=${{ matrix.llvm }}.1.0
- set LLVMInstallDir=C:\Program Files\LLVM
- call ./PCbuild/build.bat --tail-call-interp -d -p ${{ matrix.architecture }}
- call ./PCbuild/rt.bat -d -p ${{ matrix.architecture }} -q --multiprocess 0 --timeout 4500 --verbose2 --verbose3
+ choco install visualstudio2026buildtools-preview --pre -allWorkloads
+ set PATH=C:\Program Files\Microsoft Visual Studio\18\Insiders\MSBuild\Current\Bin\;%PATH%
+ ./PCbuild/build.bat --tail-call-interp --pgo -p ${{ matrix.architecture }} "/p:PlatformToolset=v145"
+ ./PCbuild/rt.bat -p ${{ matrix.architecture }} -q --multiprocess 0 --timeout 4500 --verbose2 --verbose3
 
  # No tests (yet):
- - name: Emulated Windows (release)
+ - name: Emulated Windows Clang (release)
  if: runner.os == 'Windows' && matrix.architecture == 'ARM64'
  shell: cmd
  run: |

Include/internal/pycore_ceval.h

@@ -304,9 +304,9 @@ PyAPI_FUNC(void) _PyEval_MonitorRaise(PyThreadState *tstate, _PyInterpreterFrame
 PyAPI_FUNC(bool) _PyEval_NoToolsForUnwind(PyThreadState *tstate);
 PyAPI_FUNC(int) _PyEval_UnpackIterableStackRef(PyThreadState *tstate, PyObject *v, int argcnt, int argcntafter, _PyStackRef *sp);
 PyAPI_FUNC(void) _PyEval_FrameClearAndPop(PyThreadState *tstate, _PyInterpreterFrame *frame);
-PyAPI_FUNC(PyObject **) _PyObjectArray_FromStackRefArray(_PyStackRef *input, Py_ssize_t nargs, PyObject **scratch);
+PyAPI_FUNC(PyObject **) _PyObjectArray_FromStackRefArray(_PyThreadStateImpl *_tstate, _PyStackRef *input, Py_ssize_t nargs);
 
-PyAPI_FUNC(void) _PyObjectArray_Free(PyObject **array, PyObject **scratch);
+PyAPI_FUNC(void) _PyObjectArray_Free(_PyThreadStateImpl *_tstate, PyObject **array, Py_ssize_t nargs, PyObject **temp_arr);
 
 PyAPI_FUNC(PyObject *) _PyEval_GetANext(PyObject *aiter);
 PyAPI_FUNC(void) _PyEval_LoadGlobalStackRef(PyObject *globals, PyObject *builtins, PyObject *name, _PyStackRef *writeto);

Include/internal/pycore_tstate.h

@@ -21,6 +21,9 @@ struct _gc_thread_state {
 };
 #endif
 
+/* How much scratch space to give stackref to PyObject* conversion. */
+#define MAX_STACKREF_SCRATCH 1024
+
 // Every PyThreadState is actually allocated as a _PyThreadStateImpl. The
 // PyThreadState fields are exposed as part of the C API, although most fields
 // are intended to be private. The _PyThreadStateImpl fields not exposed.
@@ -47,6 +50,8 @@ typedef struct _PyThreadStateImpl {
  struct _qsbr_thread_state *qsbr; // only used by free-threaded build
  struct llist_node mem_free_queue; // delayed free queue
 
+ PyObject *stackref_scratch[MAX_STACKREF_SCRATCH];
+ int n_stackref_scratch_used;
 #ifdef Py_GIL_DISABLED
  // Stack references for the current thread that exist on the C stack
  struct _PyCStackRef *c_stack_refs;

Misc/NEWS.d/next/Core_and_Builtins/2025-10-11-17-01-21.gh-issue-139922.RUkXyd.rst

@@ -0,0 +1 @@
+Allow building CPython with the tail calling interpreter on Visual Studio 2026 MSVC. This provides a performance gain over the prior interpreter for MSVC. Patch by Ken Jin, Brandt Bucher, and Chris Eibl. With help from the MSVC team including Hulon Jenkins.

Objects/abstract.c

@@ -205,8 +205,14 @@ PyObject_GetItem(PyObject *o, PyObject *key)
  return type_error("'%.200s' object is not subscriptable", o);
 }
 
+// MSVC fails during a tail call release build with loads of
+// error C4737: Unable to perform required tail call.
+// without using Py_NO_INLINE here, but PGO works fine.
+#if defined(_MSC_VER) && !defined(__clang__) && _Py_TAIL_CALL_INTERP && !defined(_Py_USING_PGO)
+Py_NO_INLINE
+#endif
 int
-PyMapping_GetOptionalItem(PyObject *obj, PyObject *key, PyObject **result)
+PyMapping_GetOptionalItem(PyObject *obj, PyObject *key, PyObject **restrict result)
 {
  if (PyDict_CheckExact(obj)) {
  return PyDict_GetItemRef(obj, key, result);

PCbuild/pythoncore.vcxproj

@@ -598,7 +598,9 @@
  <ClCompile Include="..\Python\bltinmodule.c" />
  <ClCompile Include="..\Python\bootstrap_hash.c" />
  <ClCompile Include="..\Python\brc.c" />
- <ClCompile Include="..\Python\ceval.c" />
+ <ClCompile Include="..\Python\ceval.c">
+ <AdditionalOptions Condition="'$(UseTailCallInterp)' == 'true' and $(PlatformToolset) != 'ClangCL'">/std:clatest %(AdditionalOptions)</AdditionalOptions>
+ </ClCompile>
  <ClCompile Include="..\Python\codecs.c" />
  <ClCompile Include="..\Python\codegen.c" />
  <ClCompile Include="..\Python\compile.c" />

Python/bytecodes.c

@@ -1982,7 +1982,7 @@ dummy_func(
  ERROR_IF(true);
  }
  PyObject *str_o = _PyUnicode_JoinArray(&_Py_STR(empty), pieces_o, oparg);
- STACKREFS_TO_PYOBJECTS_CLEANUP(pieces_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(pieces_o, oparg);
  DECREF_INPUTS();
  ERROR_IF(str_o == NULL);
  str = PyStackRef_FromPyObjectSteal(str_o);
@@ -2107,7 +2107,7 @@ dummy_func(
  values_o, 2,
  values_o+1, 2,
  oparg);
- STACKREFS_TO_PYOBJECTS_CLEANUP(values_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(values_o, oparg*2);
  DECREF_INPUTS();
  ERROR_IF(map_o == NULL);
  map = PyStackRef_FromPyObjectStealMortal(map_o);
@@ -2225,8 +2225,11 @@ dummy_func(
  }
  // we make no attempt to optimize here; specializations should
  // handle any case whose performance we care about
- PyObject *stack[] = {class, self};
- PyObject *super = PyObject_Vectorcall(global_super, stack, oparg & 2, NULL);
+ PyObject *super;
+ {
+ PyObject *stack[] = {class, self};
+ super = PyObject_Vectorcall(global_super, stack, oparg & 2, NULL);
+ }
  if (opcode == INSTRUMENTED_LOAD_SUPER_ATTR) {
  PyObject *arg = oparg & 2 ? class : &_PyInstrumentation_MISSING;
  if (super == NULL) {
@@ -2285,8 +2288,12 @@ dummy_func(
  PyObject *name = GETITEM(FRAME_CO_NAMES, oparg >> 2);
  PyTypeObject *cls = (PyTypeObject *)class;
  int method_found = 0;
- PyObject *attr_o = _PySuper_Lookup(cls, self, name,
- Py_TYPE(self)->tp_getattro == PyObject_GenericGetAttr ? &method_found : NULL);
+ PyObject *attr_o;
+ {
+ int *method_found_ptr = &method_found;
+ attr_o = _PySuper_Lookup(cls, self, name,
+ Py_TYPE(self)->tp_getattro == PyObject_GenericGetAttr ? method_found_ptr : NULL);
+ }
  if (attr_o == NULL) {
  ERROR_NO_POP();
  }
@@ -3509,10 +3516,13 @@ dummy_func(
  }
  assert(PyStackRef_IsTaggedInt(lasti));
  (void)lasti; // Shut up compiler warning if asserts are off
- PyObject *stack[5] = {NULL, PyStackRef_AsPyObjectBorrow(exit_self), exc, val_o, tb};
- int has_self = !PyStackRef_IsNull(exit_self);
- PyObject *res_o = PyObject_Vectorcall(exit_func_o, stack + 2 - has_self,
- (3 + has_self) | PY_VECTORCALL_ARGUMENTS_OFFSET, NULL);
+ PyObject* res_o;
+ {
+ PyObject *stack[5] = {NULL, PyStackRef_AsPyObjectBorrow(exit_self), exc, val_o, tb};
+ int has_self = !PyStackRef_IsNull(exit_self);
+ res_o = PyObject_Vectorcall(exit_func_o, stack + 2 - has_self,
+ (3 + has_self) | PY_VECTORCALL_ARGUMENTS_OFFSET, NULL);
+ }
  Py_XDECREF(original_tb);
  ERROR_IF(res_o == NULL);
  res = PyStackRef_FromPyObjectSteal(res_o);
@@ -3754,7 +3764,7 @@ dummy_func(
  callable_o, args_o,
  total_args | PY_VECTORCALL_ARGUMENTS_OFFSET,
  NULL);
- STACKREFS_TO_PYOBJECTS_CLEANUP(args_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(args_o, total_args);
  if (opcode == INSTRUMENTED_CALL) {
  PyObject *arg = total_args == 0 ?
  &_PyInstrumentation_MISSING : PyStackRef_AsPyObjectBorrow(arguments[0]);
@@ -3909,7 +3919,7 @@ dummy_func(
  callable_o, args_o,
  total_args | PY_VECTORCALL_ARGUMENTS_OFFSET,
  NULL);
- STACKREFS_TO_PYOBJECTS_CLEANUP(args_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(args_o, total_args);
  assert((res_o != NULL) ^ (_PyErr_Occurred(tstate) != NULL));
  DECREF_INPUTS();
  ERROR_IF(res_o == NULL);
@@ -4192,7 +4202,7 @@ dummy_func(
  ERROR_IF(true);
  }
  PyObject *res_o = tp->tp_vectorcall((PyObject *)tp, args_o, total_args, NULL);
- STACKREFS_TO_PYOBJECTS_CLEANUP(args_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(args_o, total_args);
  DECREF_INPUTS();
  ERROR_IF(res_o == NULL);
  res = PyStackRef_FromPyObjectSteal(res_o);
@@ -4263,7 +4273,7 @@ dummy_func(
  PyCFunction_GET_SELF(callable_o),
  args_o,
  total_args);
- STACKREFS_TO_PYOBJECTS_CLEANUP(args_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(args_o, total_args);
  assert((res_o != NULL) ^ (_PyErr_Occurred(tstate) != NULL));
  DECREF_INPUTS();
  ERROR_IF(res_o == NULL);
@@ -4299,7 +4309,7 @@ dummy_func(
  ERROR_IF(true);
  }
  PyObject *res_o = cfunc(PyCFunction_GET_SELF(callable_o), args_o, total_args, NULL);
- STACKREFS_TO_PYOBJECTS_CLEANUP(args_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(args_o, total_args);
  assert((res_o != NULL) ^ (_PyErr_Occurred(tstate) != NULL));
  DECREF_INPUTS();
  ERROR_IF(res_o == NULL);
@@ -4479,7 +4489,7 @@ dummy_func(
  PyCFunctionFastWithKeywords cfunc =
  _PyCFunctionFastWithKeywords_CAST(meth->ml_meth);
  PyObject *res_o = cfunc(self, (args_o + 1), nargs, NULL);
- STACKREFS_TO_PYOBJECTS_CLEANUP(args_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(args_o, total_args);
  assert((res_o != NULL) ^ (_PyErr_Occurred(tstate) != NULL));
  DECREF_INPUTS();
  ERROR_IF(res_o == NULL);
@@ -4558,7 +4568,7 @@ dummy_func(
  }
  PyCFunctionFast cfunc = _PyCFunctionFast_CAST(meth->ml_meth);
  PyObject *res_o = cfunc(self, (args_o + 1), nargs);
- STACKREFS_TO_PYOBJECTS_CLEANUP(args_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(args_o, total_args);
  assert((res_o != NULL) ^ (_PyErr_Occurred(tstate) != NULL));
  DECREF_INPUTS();
  ERROR_IF(res_o == NULL);
@@ -4657,7 +4667,7 @@ dummy_func(
  callable_o, args_o,
  positional_args | PY_VECTORCALL_ARGUMENTS_OFFSET,
  kwnames_o);
- STACKREFS_TO_PYOBJECTS_CLEANUP(args_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(args_o, total_args);
  if (opcode == INSTRUMENTED_CALL_KW) {
  PyObject *arg = total_args == 0 ?
  &_PyInstrumentation_MISSING : PyStackRef_AsPyObjectBorrow(arguments[0]);
@@ -4814,7 +4824,7 @@ dummy_func(
  positional_args | PY_VECTORCALL_ARGUMENTS_OFFSET,
  kwnames_o);
  PyStackRef_CLOSE(kwnames);
- STACKREFS_TO_PYOBJECTS_CLEANUP(args_o);
+ STACKREFS_TO_PYOBJECTS_CLEANUP(args_o, total_args);
  assert((res_o != NULL) ^ (_PyErr_Occurred(tstate) != NULL));
  DECREF_INPUTS();
  ERROR_IF(res_o == NULL);

Python/ceval.c

@@ -960,10 +960,12 @@ extern void _PyUOpPrint(const _PyUOpInstruction *uop);
 
 
 PyObject **
-_PyObjectArray_FromStackRefArray(_PyStackRef *input, Py_ssize_t nargs, PyObject **scratch)
+_PyObjectArray_FromStackRefArray(_PyThreadStateImpl *_tstate, _PyStackRef *restrict input, Py_ssize_t nargs)
 {
  PyObject **result;
- if (nargs > MAX_STACKREF_SCRATCH) {
+ /* +1 because vectorcall might use -1 to write self */
+ PyObject **target = _tstate->stackref_scratch + _tstate->n_stackref_scratch_used + nargs + 1;
+ if (target > _tstate->stackref_scratch + MAX_STACKREF_SCRATCH) {
  // +1 in case PY_VECTORCALL_ARGUMENTS_OFFSET is set.
  result = PyMem_Malloc((nargs + 1) * sizeof(PyObject *));
  if (result == NULL) {
@@ -972,7 +974,9 @@ _PyObjectArray_FromStackRefArray(_PyStackRef *input, Py_ssize_t nargs, PyObject
  result++;
  }
  else {
- result = scratch;
+ result = _tstate->stackref_scratch + _tstate->n_stackref_scratch_used;
+ _tstate->n_stackref_scratch_used += (int)nargs + 1;
+ assert(_tstate->n_stackref_scratch_used < MAX_STACKREF_SCRATCH);
  }
  for (int i = 0; i < nargs; i++) {
  result[i] = PyStackRef_AsPyObjectBorrow(input[i]);
@@ -981,10 +985,15 @@ _PyObjectArray_FromStackRefArray(_PyStackRef *input, Py_ssize_t nargs, PyObject
 }
 
 void
-_PyObjectArray_Free(PyObject **array, PyObject **scratch)
+_PyObjectArray_Free(_PyThreadStateImpl *_tstate, PyObject **array, Py_ssize_t nargs, PyObject **temp_arr)
 {
- if (array != scratch) {
- PyMem_Free(array);
+ /* -1 because we +1 previously */
+ if (array == temp_arr) {
+ _tstate->n_stackref_scratch_used -= ((int)nargs + 1);
+ assert(_tstate->n_stackref_scratch_used >= 0);
+ }
+ else {
+ PyMem_Free(array-1);
  }
 }
 

Python/ceval_macros.h

@@ -87,13 +87,15 @@
 # elif defined(_MSC_VER) && (_MSC_VER < 1950)
 # error "You need at least VS 2026 / PlatformToolset v145 for tail calling."
 # endif
-
- // Note: [[clang::musttail]] works for GCC 15, but not __attribute__((musttail)) at the moment.
-# define Py_MUSTTAIL [[clang::musttail]]
-# define Py_PRESERVE_NONE_CC __attribute__((preserve_none))
- Py_PRESERVE_NONE_CC typedef PyObject* (*py_tail_call_funcptr)(TAIL_CALL_PARAMS);
-
-# define TARGET(op) Py_PRESERVE_NONE_CC PyObject *_TAIL_CALL_##op(TAIL_CALL_PARAMS)
+# if defined(_MSC_VER) && !defined(__clang__)
+# define Py_MUSTTAIL [[msvc::musttail]]
+# define Py_PRESERVE_NONE_CC __preserve_none
+# else
+# define Py_MUSTTAIL __attribute__((musttail))
+# define Py_PRESERVE_NONE_CC __attribute__((preserve_none))
+# endif
+ typedef PyObject *(Py_PRESERVE_NONE_CC *py_tail_call_funcptr)(TAIL_CALL_PARAMS);
+# define TARGET(op) Py_NO_INLINE PyObject *Py_PRESERVE_NONE_CC _TAIL_CALL_##op(TAIL_CALL_PARAMS)
 # define DISPATCH_GOTO() \
  do { \
  Py_MUSTTAIL return (((py_tail_call_funcptr *)instruction_funcptr_table)[opcode])(TAIL_CALL_ARGS); \
@@ -401,17 +403,14 @@ do { \
 
 /* Stackref macros */
 
-/* How much scratch space to give stackref to PyObject* conversion. */
-#define MAX_STACKREF_SCRATCH 10
 
 #define STACKREFS_TO_PYOBJECTS(ARGS, ARG_COUNT, NAME) \
-/* +1 because vectorcall might use -1 to write self */ \
- PyObject *NAME##_temp[MAX_STACKREF_SCRATCH+1]; \
- PyObject **NAME = _PyObjectArray_FromStackRefArray(ARGS, ARG_COUNT, NAME##_temp + 1);
+_PyThreadStateImpl *_tstate = (_PyThreadStateImpl *)tstate; \
+ PyObject **NAME##_temp = _tstate->stackref_scratch + _tstate->n_stackref_scratch_used;  \
+ PyObject **NAME = _PyObjectArray_FromStackRefArray(_tstate, ARGS, ARG_COUNT);
 
-#define STACKREFS_TO_PYOBJECTS_CLEANUP(NAME) \
- /* +1 because we +1 previously */ \
- _PyObjectArray_Free(NAME - 1, NAME##_temp);
+#define STACKREFS_TO_PYOBJECTS_CLEANUP(NAME, ARG_COUNT) \
+ _PyObjectArray_Free(_tstate, NAME, ARG_COUNT, NAME##_temp);
 
 #define CONVERSION_FAILED(NAME) ((NAME) == NULL)