Condition variable examples can be improved to show cv's main purpose - handling variables under a lock

I think this section Condition Objects can be improved to show in examples how shared state can be handled with condition objects:

https://docs.python.org/3/library/threading.html#condition-objects

This section does mention that condition variables are supposed to be evaluated/modified under a lock, but does not give any examples on how they are supposed to be handled.

Also, worth noting that the term condition variable in original contexts, such as C++ std::condition_variable or POSIX' pthread_cond_wait, refers to the machinery that provides atomic access to some shared state, not like Python does, calling shared state as condition variables protected by condition objects.

One would typically use a condition variable for things like waiting on non-waitable conditions, like a plain in-memory queue or an app stop request. So, a condition variable could be used in order to guarantee atomic handling of both conditions like this (ignoring exceptions):

cv.acquire()
while not stop_app:
    if myq.is_empty():
        cv.wait()       # unlocks; allows other threads queue work and stop app
                        # locks again
        continue        # re-evaluate both conditions under the lock

    req = myq.get()     # myq has no locking on its own
    cv.release()

    process(req)        # expensive - must be outside the lock
    cv.acquire()
cv.release()

The queue and the application stop request represent the shared state protected by the condition variable. Something along these lines would be helpful on this page, perhaps with a better structured with block.

Also, current examples, like this one:

with cv:
    while not an_item_is_available():
        cv.wait()
    get_an_available_item()

, do not highlight that an_item_is_available may only be an in-memory operation and if something expensive is done there, it will block the app from being able to queue new work or stop.

The example should show how the work item is retrieved and how it is processed. An assignment should be made where get_an_available_item is called and same emphasis can be provided that it must be an in-memory operation that cannot block at all, not even with a timeout.

The work item that was obtained above should be passed into some kind of a processing function outside of the with cv: block, so items are processed outside of the lock.

This is just a suggestion. If you feel current description is good enough for the intended audience, go ahead and close this issue.

从 Python threading 文档的 Condition Objects 部分开始，并将现有示例与报告中提到的共享状态用例进行比较。修改示例，使其展示受保护的内存中状态、在条件锁下进行检索，以及在锁外进行处理；完成的标准是文档清楚地解释锁的边界和重新评估行为。