Add a typed exception for concurrent.futures executor shutdown
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 35.9k
- PR merge metrics
- PR metrics pending
Description
Proposal:
concurrent.futures.Executor.submit() implementations currently raise a generic RuntimeError when work is submitted after executor shutdown. For example, ThreadPoolExecutor.submit() raises one of these messages:
RuntimeError("cannot schedule new futures after shutdown")
RuntimeError("cannot schedule new futures after interpreter shutdown")
This makes it difficult for callers to distinguish expected executor lifecycle failures from unrelated RuntimeErrors without matching exception message strings:
try:
future = executor.submit(fn)
except RuntimeError as exc:
if str(exc) in {
"cannot schedule new futures after shutdown",
"cannot schedule new futures after interpreter shutdown",
}:
handle_executor_shutdown(exc)
else:
raise
It would be useful to expose a typed exception for this condition, for example:
class ExecutorShutdownError(RuntimeError):
pass
Then executor implementations could raise ExecutorShutdownError for explicit shutdown and interpreter-shutdown submission failures. Because it would subclass RuntimeError, existing callers catching RuntimeError would remain compatible, while callers that need precise handling could avoid brittle string matching:
try:
future = executor.submit(fn)
except concurrent.futures.ExecutorShutdownError:
handle_executor_shutdown()
This would mirror the existing benefit of typed executor failures such as BrokenExecutor, where callers can distinguish executor state from arbitrary runtime failures without inspecting exception text.
Has this already been discussed elsewhere?
This is a minor feature, which does not need previous discussion elsewhere
Links to previous discussion of this feature:
None. I searched existing CPython issues for ExecutorShutdownError, cannot schedule new futures after shutdown, cannot schedule new futures after interpreter shutdown, and related concurrent.futures RuntimeError shutdown exception type wording. I found issues about shutdown behavior itself, but not this typed-exception API request.
Linked PRs
- gh-153003
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the concurrent.futures.Executor.submit() implementations and the existing BrokenExecutor API. Review linked PR gh-153003 and its related tests; done means shutdown submissions expose a dedicated exception while preserving RuntimeError compatibility and covering explicit and interpreter shutdown cases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100