Add `sys._is_gil_enabled()`

[colesbury]

Feature or enhancement

I propose adding a new function to the sys module to check if the GIL is current enabled:

sys._is_gil_enabled() -> bool

Return True if the GIL is currently enabled and False if the GIL is currently disabled.

The function would always return True in builds that do not support free-threading. In the free-threaded build, the the GIL might be dynamically enabled or disabled depending on imported modules.

EDIT: Changed name to use underscore prefix

Linked PRs

• gh-117514: Add sys._is_gil_enabled() function #118514

[zooba]

What do you expect developers to do with this value? Is it merely for reporting details about bugs? Or is there some programmatic reason you may want to know this?

[gpshead]

I'd expect likely just reporting. Similar to things like sys.is_stack_trampoline_active(). It isn't an API likely to be logically useful to most code. But the reporting aspect is important, especially for test runners.

[colesbury]

I think the diagnostic and bug reporting uses are most straight-forward: is the GIL really disabled? Especially because it looks like we will be temporarily enabling the GIL around imports.

I think it might also be useful in a few cases for choosing reasonable defaults: i.e., does a thread-pool or multiprocessing backend make more sense as a default in some library (like PyTorch data loaders or joblib).

[zooba]

I fear it won't be particularly useful for either of those cases with the current proposed (temporary?) semantics.

Reporting feels like it ought to be "was the GIL enabled when X went wrong", while selecting defaults feels like "will the GIL be enabled under normal operation".

Otherwise the semantics of "don't call this during import" are going to be very unhelpful, both to explain and to reveal internal behaviour details and require users to design around them.

How about a CPython-specific sys._is_gil_enabled() to return the status right now, and a more generic sys.is_free_threaded() (that could also be implemented in other runtimes) to return the intent of the runtime?

(FWIW, I'd have argued is_stack_trampoline_active() should have an underscore, like sys._getframe() and sys._git, but I missed that proposal.)

[colesbury]

That seems like a more confusing API to me. I don't think there's a sufficient need for sys.is_free_threaded() and "intent of the runtime" strikes me as too vague of a concept to be useful. We already have other mechanisms for querying the build configuration and runtime initialization flags.

What do you mean by "don't call this during import"?

[colesbury]

We are only planning to do the temporary GIL enabling around imports of C-API extensions, not Python modules so I don't think there's any reason not to call sys.is_gil_enabled() during an import. I don't think users have to design around it.

[zooba]

We already have other mechanisms for querying the build configuration and runtime initialization flags.

Mechanisms that don't exist in, say, IronPython, which is nonetheless free threaded, and given the choice between threads or processes you would likely choose threads for similar kinds of tasks that you would under free-threaded CPython.

The sys module is supposed to be consistent across implementations, so it's worth considering how other implementations will explain and handle the function.

[colesbury]

The sys module is supposed to be consistent across implementations, so it's worth considering how other implementations will explain and handle the function.

I agree, and I think that sys.is_gil_enabled() is straight-forward to use and explain: if implemented in IronPython it can always return False. If implemented in PyPy, it can always return True.

[zooba]

It just feels a bit weird to suddenly introduce "GIL" as a Python-wide concept when previously it was only ever a CPython implementation detail (a public one, to be sure, but not a cross-implementation concern in any way). Especially since the plan is to eventually have everyone return False all the time.

Why is it so bad to make it a documented underscored function _is_gil_enabled? (And thereby not require other implementations to worry about it.)

[colesbury]

I prefer sys.is_gil_enabled, but I don't think having only the underscored sys._is_gil_enabled() is so bad.

It's more the combination of sys._is_gil_enabled() and sys.is_free_threaded that I think is confusing.

[gpshead]

It's also fair to just start with the _is_gil_enabled() name so that we can change this later. (feel free to document that _ API, just mention that its existence or name may change in future minor python versions so people who want to use it should check for it). We can base a future decision to make a non _ name based on what we find users actually found a need for.

[colesbury]

I've updated the issue to sys._is_gil_enabled().