{"slug": "threadpoolexecutor-result-timeout-1-left-4-calls-running", "title": "ThreadPoolExecutor result(timeout=1) Left 4 Calls Running", "summary": "A developer's tests on CPython 3.14.4 show that ThreadPoolExecutor's future.result(timeout=1) only stops the caller from waiting, not the underlying work: four agent tool calls that each raised TimeoutError after 1 second all ran their full 5 seconds, future.cancel() returned False, and a subsequent 0.1-second call on the same pool waited 1.10 seconds for a free worker. The asyncio equivalent, asyncio.wait_for(asyncio.to_thread(...)), timed out at 1.00 second but left the thread running, and asyncio.run() did not return until 8.10 seconds because shutdown waits on the default executor's threads. The developer's fix runs each tool in a spawned child process and terminates the worker on timeout.", "body_md": "`future.result(timeout=1)` raises `TimeoutError` after one second, but the thread keeps running the call to the end, and `future.cancel()` returns `False` because the work already started; if a tool call must really stop, run it in a child process and terminate that process on timeout. In my test, four agent tool calls that each \"timed out\" after 1 s all ran their full 5 s, and the next 0.1 s call on the same pool waited 1.10 s for a free thread.\n\nThis story was written with the assistance of an AI writing program. All numbers come from CPython 3.14.4 on Linux 7.0, and both scripts ran twice with identical output.\n\nHere is the version that actually stops the work. It is the code I now use for agent tools that wrap slow, uncooperative functions:\n\n``` python\nimport multiprocessing as mp\nimport time\ndef tool(secs):\n    time.sleep(secs)\n    return \"ok\"\ndef run_tool(fn, *args, timeout):\n    ctx = mp.get_context(\"spawn\")\n    with ctx.Pool(1) as pool:\n        res = pool.apply_async(fn, args)\n        return res.get(timeout=timeout)  # leaving the with-block terminates the worker\n```\n\nThe rest of this post is why the thread version cannot do this, and what it costs you when you try.\n\nYesterday I wrote about `subprocess.run(timeout=1)` leaving orphans behind. The same question applies one layer up. A lot of agent frameworks run tool functions in a `ThreadPoolExecutor` so the event loop stays free, then put a timeout on the future. I wanted to know what that timeout actually does.\n\nThe test is small: a tool that sleeps 5 seconds and records when it finishes, a pool with four workers, and four calls, each awaited with `result(timeout=1)`. Then a fresh 0.1 s call on the same pool, then the asyncio equivalent, `asyncio.wait_for(asyncio.to_thread(...), timeout=1)`.\n\nFrom the first run, unedited:\n\n```\nresult(timeout=1): 4 TimeoutError by 4.00s, cancel()=False, running=4, threads=5\nfresh 0.1s call on same pool returned after 1.10s\nwait_for(to_thread, timeout=1): TimeoutError at 1.00s\nasyncio.run returned at 8.10s\ncompleted in background: [('call0', 5.0), ('call1', 5.0), ('call2', 5.0), ('call3', 5.0), ('fresh', 5.1), ('async', 8.1)]\n```\n\nEvery timeout fired on schedule. None of them stopped anything. All four calls finished at 5.0 s and wrote their results into a list nobody was reading. If those calls had been sending emails or writing rows, all four side effects would have happened after the caller had already logged \"tool timed out\".\n\nThe `concurrent.futures` docs are honest about this: \"If the call is currently being executed or finished running and cannot be cancelled then the method will return False.\" In other words, it removes queued work, nothing else. Python has no supported way to kill a thread. The timeout on `result()` is a timeout on your wait, not on the work.\n\nThat distinction is easy to miss because the exception type looks like a verdict. `TimeoutError` reads as \"the call was stopped\". It means \"I stopped waiting\".\n\nThe second line is the one that would hurt in production. After four timeouts the pool looked idle from the caller's side, but all four workers were still busy. A 0.1 s call submitted at that point sat in the queue until a worker came free at the 5 s mark and returned after 1.10 s.\n\nScale that up. An agent that retries a slow tool a few times can fill the pool with zombie calls, and then every fast tool queues behind them. Nothing errors. Latency just climbs, and the traces show \"timeout\" on the slow calls and \"slow\" on the fast ones, which points you at the wrong thing.\n\n`asyncio.wait_for(asyncio.to_thread(tool, 3), timeout=1)` raised at 1.00 s, as advertised. The thread kept going. Then `asyncio.run()` itself did not return until 8.10 s, because on shutdown it waits for the default executor's threads to finish. So the \"1 second\" timeout turned into a 2 s stall at exit, well after the caller moved on. In a CLI agent that is the \"why does it hang after printing the answer\" bug.\n\nThe fix at the top swaps the thread for a one-worker process pool. On timeout, leaving the `with` block calls `terminate()` on the worker, so the work really ends. Its output, twice:\n\n```\nTimeoutError at 1.04s, children left: 0\nok 0.16s\n```\n\nThe price is about 0.15 s of `spawn` start-up per call and the usual pickling rules for arguments and results. For tools that call slow external code, that is cheap. For tools that are just HTTP requests, a better fix is a real timeout inside the call, such as an httpx timeout or `asyncio.timeout` around an async client, because cooperative cancellation never leaves a half-done write behind a killed process.\n\n`future.result(timeout=N)` and `asyncio.wait_for(to_thread(...))` time out your wait, not the work. The function runs to completion.`future.cancel()` returns `False` once the call has started. Do not treat it as a kill switch.`asyncio.run()` waits for executor threads at exit, so a timed-out thread can stall shutdown.", "url": "https://wpnews.pro/news/threadpoolexecutor-result-timeout-1-left-4-calls-running", "canonical_source": "https://dev.to/acemeridian/threadpoolexecutor-resulttimeout1-left-4-calls-running-4d8d", "published_at": "2026-11-21 05:02:54+00:00", "updated_at": "2026-11-21 05:11:58.840596+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["ThreadPoolExecutor", "asyncio", "CPython", "Python", "multiprocessing"], "also_reported_by": [], "takeaway": "ThreadPoolExecutor's result(timeout=1) only bounds the wait, not the work: four 5-second tool calls all completed after timing out and blocked a fresh 0.1-second call for 1.10 seconds, so run uncooperative tools in a spawned child process and terminate it on timeout.", "recommendation": {"advice": "Run slow, uncooperative agent tool calls in a spawned child process and terminate the worker on timeout, since ThreadPoolExecutor timeouts leave the thread running and starve the pool.", "playbook": "agent-architecture", "playbook_url": "https://wpnews.pro/playbooks/agent-architecture"}, "alternates": {"html": "https://wpnews.pro/news/threadpoolexecutor-result-timeout-1-left-4-calls-running", "markdown": "https://wpnews.pro/news/threadpoolexecutor-result-timeout-1-left-4-calls-running.md", "text": "https://wpnews.pro/news/threadpoolexecutor-result-timeout-1-left-4-calls-running.txt", "jsonld": "https://wpnews.pro/news/threadpoolexecutor-result-timeout-1-left-4-calls-running.jsonld"}}