Add a C API to assign a new version to a PyTypeObject

[swtaarrs]

Feature or enhancement

I would like to add an API function like this:

/* Attempt to assign a version tag to the given type.
 *
 * Returns 1 if the type already had a valid version tag or a new one was
 * assigned, or 0 if a new tag could not be assigned.
 */
PyAPI_FUNC(int) _PyType_AssignVersionTag(PyTypeObject* type);

It would be a thin wrapper around the existing assign_version_tag function, and is modeled after a similar function we added to Cinder as part of facebookincubator/cinder@43c4e2d.

Pitch

Cinder (and possibly other JITs or optimizing interpreters) would benefit from being able to ensure that type has a valid version tag without having to call _PyType_Lookup() just for the version-assigning side-effect. We rely on notifications from PyType_Modified() to invalidate code in our JIT when types change, and this only works when the types in question have valid version tags.

Previous discussion

There's no written discussion I'm aware of, but @carljm and @markshannon have discussed this offline.

Linked PRs

• gh-103091: Add PyUnstable_Type_AssignVersionTag #103095

[encukou]

AFAIK, version tags are an implementation detail. For anything except JITs/optimizers, PyType_Modified() should be enough API.
IMO it would make sense to put this function in the unstable API. Name the function PyUnstable_Type_AssignVersionTag to do that.

[carljm]

I suspect it would also make more sense for the declaration to live in Include/cpython/object.h rather than Include/object.h, though I guess this isn't strictly required?

[swtaarrs]

#103095 is merged. Thanks @encukou and @carljm!

[brandtbucher]

I was just bit by this API's somewhat odd return value. Typically we return 0 on success and -1 on failure, but this returns 1 on success and 0 on failure.

Perhaps it should be changed?

[carljm]

I'm glad you're finding uses for this API :)

The PR to expose this function outside typeobject.c just passed through the existing return value convention from the pre-existing staticassign_version_tag function, which has been there for a long time; I don't think changing it was ever considered.

I'm not sure how consistent the convention is; e.g. the compiler always returns 0 on failure and 1 on success. (EDIT: never mind, looks like this was changed in #100010!) Also, -1 often signifies "exception is set," but this API never sets an exception, it's just indicating whether a version tag was successfully set.

No strong feelings here.

[erlend-aasland]

Also, -1 often signifies "exception is set," but this API never sets an exception, it's just indicating whether a version tag was successfully set.

What if we need to change the implementation in the future (because of runtime changes or whatever) and we end up having to use an internal API that can set an exception? If we design this API to always succeed, we have two options: swallow the exception before returning, or add a new API that can return with an exception set. See also the issue about infallible APIs in the C API workgroup repo.