bpo-39947: Add PyThreadState_SetTrace() function

[vstinner]

Add new PyThreadState_SetProfile() and PyThreadState_SetTrace()
functions to set the profile and the trace function of a Python
thread state.

• Rename _PyEval_SetProfile() to PyThreadState_SetProfile().
• Rename _PyEval_SetTrace() to PyThreadState_SetTrace().
• Rename is_tstate_valid() to _PyThreadState_CheckConsistency().

https://bugs.python.org/issue39947

[vstinner]

PyThreadState_SetProfile() is needed by the Python yappi profiler:

ts->c_profilefunc = _yapp_callback;

Source: https://github.com/sumerc/yappi/blob/8bf7a650066f104f59c3cae4a189ec15e7d51c8c/yappi/_yappi.c#L1258

[vstinner]

See also discussion at: https://bugs.python.org/issue43760

[vstinner]

cc @markshannon

[vstinner]

I don't understand well the relationship between PyThreadState.c_tracefunc and PyFrameObject.f_trace. Currently, sys.settrace() function suggests setting frame.f_trace = tracefunc directly in Python: https://docs.python.org/dev/library/sys.html#sys.settrace

[vstinner]

PyThreadState_SetProfile() is needed by the Python yappi profiler:

I'm not sure if yappi can use it directly, since PyThreadState_SetProfile() requires to hold the GIL. But it's more a yappi issue, than an API issue IMO.

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[JimJJewett]

I think it would be helpful to add a 3rd column stating which of the trace/profile functions see each event type. In case this isn't pointing to the right place, Doc/c-api/init.rst 1556 or 1616 depending on before/after

[JimJJewett]

I would add "(replacing _PyEval_SetProfile)" and "(replacing _PyEval_SetTrace)" since those are likely to be the names people have if they are searching for changes, instead of just reading in advance.

[JimJJewett]

Also mention renaming and move is_tstate_valid to _PyThreadState_CheckConsistency

[vstinner]

is_tstate_valid() is a static function, it cannot be used outside ceval.c. We don't document changes which don't affected the public C API.

[vstinner]

I would add "(replacing _PyEval_SetProfile)" and "(replacing _PyEval_SetTrace)" since those are likely to be the names people have if they are searching for changes, instead of just reading in advance.

Usually, we never mention private functions in the changelog.

[vstinner]

I think it would be helpful to add a 3rd column stating which of the trace/profile functions see each event type. In case this isn't pointing to the right place, Doc/c-api/init.rst 1556 or 1616 depending on before/after

If you consider that the doc should be completed, please open a new issue. I don't see a direct relationship between your comment and my PR adding new functions.

[vstinner]

I'm not convinced that there are 3rd party Python projects which need and will use this function. I prefer to close this PR for now. I may revisit it later, if more users of this function are discovered.