thread_pool: document shutdown contract

Spell out the "producers stop before destruction" requirement at the
class level so callers know that enqueue_task returns a future that
will throw broken_promise, and enqueue_work* variants silently drop
work, if they race the destructor.
This commit is contained in:
Antonio S. Musumeci 2026-04-18 17:49:43 -04:00
parent fbf69071d2
commit 1b158549b8

View file

@ -46,6 +46,18 @@ struct ThreadPoolTraits : public moodycamel::ConcurrentQueueDefaultTraits
};
// Shutdown contract:
// Callers must stop submitting work before destroying the pool.
// The destructor does not drain the queue: tasks enqueued but not
// yet dequeued when the destructor runs are discarded. For
// enqueue_task this means the std::promise is destroyed unfulfilled
// and the caller's future.get() throws std::future_error with
// broken_promise. enqueue_work* variants have no return value and
// the work is silently dropped.
//
// An enqueue racing with the destructor is otherwise safe — the
// BoundedQueue destructor runs only after all workers are joined, so
// the queue is not accessed concurrently during teardown.
class ThreadPool
{
public: