Incomplete example in concurrent.future documentation

[maininformer]

Documentation

The second example here is missing a result call.

def wait_on_future():
    f = executor.submit(pow, 5, 2)
    # This will never complete because there is only one worker thread and
    # it is executing this function.
    print(f.result())

executor = ThreadPoolExecutor(max_workers=1)
executor.submit(wait_on_future)

Should be

def wait_on_future():
    f = executor.submit(pow, 5, 2)
    # This will never complete because there is only one worker thread and
    # it is executing this function.
    print(f.result())

executor = ThreadPoolExecutor(max_workers=1)
(executor.submit(wait_on_future)).result()

Linked PRs

• gh-141617: Add missing result() call in concurrent.futures example #141620

[Yashp002]

@maininformer ,I've submitted PR #141620 to fix this. Added the missing .result() call to complete the deadlock example.

[picnixz]

What about the first example then? none of them have a .result() call. I wonder whether we really want to call .result() as this creates a deadlock for the user. Maybe it's better to have task = executor.submit(...) followed by # task.result() would deadlock

[Yashp002]

Thanks for the feedback. Should I update the first example and both code blocks to follow this style (task = executor.submit(...) followed by a comment about deadlock), or just revise the specific one? Happy to make the change as you prefer.

[picnixz]

I don't know. I'm not very happy to give an example which, when you run it, gives a deadlock. Because this means hitting Ctrl+C multiple times, and ending up having a somewhat incomprehensible traceback.

Let's ask other core devs on the stance to take (@vstinner @ZeroIntensity)

[maininformer]

What about the first example then? none of them have a .result() call. I wonder whether we really want to call .result() as this creates a deadlock for the user. Maybe it's better to have task = executor.submit(...) followed by # task.result() would deadlock

FWIW, The first examples also calls .result but in the body of the other task. It does indeed produce a deadlock when run. cc @Yashp002, I don't think we want to touch the first example because of this.

[picnixz]

AFAICT, Both examples would deadlock. The second example has a maxworker of 1 so if you run .result on the submitted task you'll wait for the body to be executed.

[Yashp002]

Since both examples would deadlock with .result() in an event loop, would it make sense to add a warning note like:

.. warning::
Calling .result() on a task submitted from within an event loop will cause a deadlock, as the event loop thread will block waiting for itself to complete the task.

[picnixz]

I don't think it's good to be as generic here or use a warning which would be visually disruptive. A simple sentence in the paragraph itself should suffice but I don't have a good formulation. I think it's just better to either leave it as is, or add a line # calling task.result() would deadlock just after submitting the outer tasks but I'd like my fellow core devs to give their opinion here.

@Yashp002 While I appreciate your dedication for contributing, please avoid rushing into PRs before the issue has been discussed and a consensus on how to proceed has been reached.

[Yashp002]

@picnixz Yeah i get it, thanks for the clarification I'll wait for the discussion to avail a conclusion before jumping in. Let me know if there's any contribution I can make once a conclusion has been reached, tysm.