gh-141004: Document missing PyThread* APIs

[ZeroIntensity]

• Issue: Document the entire C API #141004

---

📚 Documentation preview 📚: https://cpython-previews--141810.org.readthedocs.build/en/141810/c-api/init.html#legacy-locking-apis

[ZeroIntensity]

@colesbury, if you have time, I'd really appreciate your expertise here (especially on the PyThread_exit_thread warning).

[vstinner]

It can be any signal but the signal handler should raise an exception. Well, CTRL+C is any example which raises KeyboardInterrupt.

[ZeroIntensity]

So the caller just needs to call PyErr_CheckSignals as well?

[colesbury]

PyThread_acquire_lock_timed doesn't set an exception. If PyThread_acquire_lock_timed returns PY_LOCK_INTR, the caller typically checks for ctrl-c (and other signals) with Py_MakePendingCalls(). The typical pattern is:

cpython/Modules/_threadmodule.c

Lines 98 to 112 in 9524203

	/* first a simple non-blocking try without releasing the GIL */
	r = PyThread_acquire_lock_timed(lock, 0, 0);
	if (r == PY_LOCK_FAILURE && microseconds != 0) {
	Py_BEGIN_ALLOW_THREADS
	r = PyThread_acquire_lock_timed(lock, microseconds, 1);
	Py_END_ALLOW_THREADS
	}
	if (r == PY_LOCK_INTR) {
	/* Run signal handlers if we were interrupted. Propagate
	* exceptions from signal handlers, such as KeyboardInterrupt, by
	* passing up PY_LOCK_INTR. */
	if (Py_MakePendingCalls() < 0) {
	return PY_LOCK_INTR;
	}

[ZeroIntensity]

Added a note about Py_MakePendingCalls, let me know what either of you think about the wording.