Update some comments

Author: JukkaL

mypyc/lib-rt/threading/librt_threading.c

@@ -125,9 +125,10 @@ typedef struct {
     // This backend is only selected when the GIL is enabled, so this flag is a
     // plain int relying on the GIL for serialization: it is only ever touched
     // with the GIL held (the blocking sem_wait drops the GIL, but the flag
-    // store happens after the GIL is reacquired). CPython keeps the same flag
-    // as a plain `char` in its _thread lock wrapper (Modules/_threadmodule.c)
-    // for exactly this purpose.
+    // store happens after the GIL is reacquired). This mirrors the old
+    // PyThread_type_lock wrapper bookkeeping used by CPython 3.12 and earlier,
+    // where _thread lock kept a plain `char locked` for sanity checks and
+    // locked().
     int locked;
 } LockObject;
 
@@ -451,7 +452,8 @@ Lock_is_locked(LockObject *self)
     return result;
 #elif defined(LOCK_BACKEND_SEM)
     // The flag is GIL-serialized (see the struct comment); locked() is a
-    // plain read, matching CPython's _thread lock.
+    // plain read, matching the old CPython _thread lock bookkeeping described
+    // above.
     return self->locked != 0;
 #else  // pthread mutex + condvar fallback
     // `locked` is only ever accessed under `mut`; take it for a clean read.

mypyc/primitives/librt_threading_ops.py

@@ -13,7 +13,7 @@
     dependencies=[LIBRT_THREADING],
 )
 
-# Lock.acquire() -- blocking acquire, always returns True
+# Lock.acquire() -- blocking acquire, returns True unless it raises
 lock_acquire_op = method_op(
     name="acquire",
     arg_types=[lock_rprimitive],

mypyc/test-data/run-threading.test

@@ -54,7 +54,7 @@ def test_contention() -> None:
 
 def test_cross_thread_release() -> None:
     # threading.Lock is unowned: a lock acquired on one thread may be
-    # released from another. A thread blocked in acquire() must then wake up.
+    # released from another, after which another thread can acquire it.
     import threading
     lock = Lock()
     assert lock.acquire()
@@ -71,7 +71,7 @@ def test_cross_thread_release() -> None:
     t = threading.Thread(target=releaser)
     t.start()
     started.wait()
-    # Blocks until releaser releases the lock on the other thread.
+    # This may block until releaser releases the lock on the other thread.
     assert lock.acquire()
     t.join()
     assert released.is_set()