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.

Comece pela seção «Condition Objects» da documentação de threading do Python e compare o exemplo existente com o caso de uso de estado compartilhado relatado. Revise o exemplo para mostrar um estado protegido em memória, a recuperação sob o bloqueio da condição e o processamento fora dele; estará concluído quando a documentação explicar claramente o limite do bloqueio e o comportamento de reavaliação.