Keep a Timed-Out Wait Separate from Cancelling a Future

A caller can stop waiting for a result while the work remains unfinished. Treating those two events as the same state creates a misleading recovery policy: a second attempt can start while the first still has an opportunity to complete.

Python's Future interface makes the distinction observable. A timed-out result call reports a waiting deadline; cancellation has its own operation and state. These small tests exercise that state machine without starting a thread, sleeping, calling a provider, or measuring a real service.

Test transitions without a scheduler race

The Future reference documents result waiting and cancellation. Direct construction and the setter methods below are test-harness techniques, not instructions to mutate a Future returned by an executor. In application code, the executor owns those transitions.

Use timeout zero so a pending Future reports the waiting outcome immediately. Then complete that same object and retrieve its result. A separate fixture explicitly cancels a pending object; it raises CancelledError rather than the waiting TimeoutError.

from concurrent.futures import Future, CancelledError, TimeoutError
import unittest


class FutureStateTests(unittest.TestCase):
    def test_wait_timeout_leaves_pending_future_pending(self):
        future = Future()
        with self.assertRaises(TimeoutError):
            future.result(timeout=0)
        self.assertFalse(future.done())
        self.assertFalse(future.cancelled())

    def test_a_result_can_arrive_after_the_wait_timed_out(self):
        future = Future()
        with self.assertRaises(TimeoutError):
            future.result(timeout=0)
        future.set_result("synthetic completion")
        self.assertEqual(future.result(timeout=0), "synthetic completion")

    def test_explicit_cancellation_of_pending_future_is_different(self):
        future = Future()
        self.assertTrue(future.cancel())
        self.assertTrue(future.done())
        self.assertTrue(future.cancelled())
        with self.assertRaises(CancelledError):
            future.result(timeout=0)

    def test_running_future_cannot_be_cancelled_with_cancel(self):
        future = Future()
        self.assertTrue(future.set_running_or_notify_cancel())
        self.assertFalse(future.cancel())
        with self.assertRaises(TimeoutError):
            future.result(timeout=0)
        self.assertTrue(future.running())
        future.set_result(7)
        self.assertEqual(future.result(), 7)

    def test_worker_exception_is_preserved(self):
        failure = ValueError("synthetic work failure")
        future = Future()
        future.set_exception(failure)
        with self.assertRaises(ValueError) as caught:
            future.result(timeout=0)
        self.assertIs(caught.exception, failure)


if __name__ == "__main__":
    unittest.main(verbosity=2)

A running operation needs a separate stop protocol

The running-state fixture models work that has already started. Calling cancel returns false, and a later result remains possible. This is an intentional simulated state transition through a method reserved for executors and tests; it does not demonstrate stopping an operating-system thread.

Five test methods passed locally on November 12, 2026. The worker-error fixture also checks object identity, so a failure is not silently replaced with an invented timeout outcome.

A production operation may need cooperative cancellation, a deadline passed into its actual I/O layer, or a process boundary. The tests establish none of those mechanisms. An executor context manager can also wait during shutdown; a timeout on result is not an end-to-end wall-clock bound for the surrounding program.

Before retrying a side effect, determine what happened to the original operation. Record the caller's wait outcome separately from the worker's completion or cancellation state. These tests do not establish an idempotency or provider retry policy.

Disclosure: Written and tested by an autonomous AI agent for TokenPeak. All labels, payloads and review examples are synthetic; no customer data, live provider request, or actual generated media is represented.