Retrieving Task Results with `std::future`

The Asynchronous Communication Channel: Promise and Future

At its heart, the std::promise / std::future pair is a one-time, one-way communication channel between two threads.

• One thread, the producer, holds the std::promise. It performs a computation and eventually fulfills the promise by setting a value or an exception.
• Another thread, the consumer, holds the std::future. It can query the future for the result. If the result isn't ready, the future will block the consumer thread until the producer fulfills the promise.

This communication happens through a shared state that is typically allocated on the heap. Let's start with a great video that uses a memorable analogy to explain this core concept.

The key elements from the "mailbox" analogy map directly to C++ concurrency primitives:

• The Mailbox: The heap-allocated shared state object.
• Touching the Mailbox: Access is protected by a std::mutex.
• The Flag: A boolean flag indicating if the result is ready.
• Banging the Cymbals: Notifying the waiting thread via a std::condition_variable.

This sequence diagram formalizes the interaction:

Building a Future: The Internals

Now, let's build our own simplified Future to truly understand the mechanics. A naive approach might be to store the result, thread, and synchronization primitives directly inside the Future object itself. However, this runs into a critical issue, especially when you want your Future objects to be movable.

The following article walks through this exact design process, identifying the pitfalls and arriving at the correct, robust solution.

As the article explains, the solution is to decouple the Future object from the data it represents.

1. The Control Block (Shared State): A non-movable, non-copyable object allocated on the heap that contains the actual result, exception pointer, mutex, condition variable, and ready flag.
2. The Future/Promise Objects: Lightweight, movable "view" objects that hold a std::shared_ptr to the single control block.

This design ensures that even if the Future or Promise objects are moved between functions or threads, the shared_ptrs inside them always point to the same stable memory location—the control block.

Dissecting the Control Block

Let's examine the implementation of this shared state, or control block. The video from Arthur O'Dwyer and the article both provide excellent code examples.

Let's summarize the logic for the two most important operations:

promise::set_value(value) (Producer Thread)

1. Acquire a lock on the shared state's mutex.
2. Check if the value has already been set. If so, throw an exception (a promise can only be fulfilled once).
3. Move the value into the shared state's result member.
4. Set the ready flag to true.
5. Unlock the mutex.
6. Call notify_one() on the condition variable to wake up the (potentially waiting) future.

future::get() (Consumer Thread)

1. Acquire a lock on the shared state's mutex.
2. Use the condition variable's wait() method. The wait function will atomically unlock the mutex and suspend the thread until it is notified. Crucially, it waits on a predicate: while (!ready) { wait(); }. This handles spurious wakeups; the thread only proceeds if the ready flag is actually true.
3. Once woken up and the ready flag is true, the wait returns, with the lock re-acquired.
4. Check if an exception was stored instead of a value. If so, rethrow it.
5. Move the result out of the shared state and return it.
6. The lock is released when the unique_lock goes out of scope.

An Alternative Thread Pool API

In our last lesson, we used a std::shared_ptr<std::packaged_task<...>> to achieve type erasure. Now that we understand the promise/future mechanism so well, we can explore an alternative design that uses std::promise more directly. This approach is inspired by modern APIs like Boost.Asio.

This design involves:

1. A task queue that only stores std::packaged_task<void()> to keep the worker logic simple.
2. An overloaded global post function that serves as the submission interface.
3. A special "tag" struct (use_future_tag) to select the overload that returns a std::future.

Let's break down the key part of that implementation for a task that returns a value:

// Simplified from the article
template <class Executor, class Fn>
auto post(Executor& exec, std::tuple<use_future_tag, Fn>&& tpl)
{
    // 1. Get the original function
    auto&& [_, func] = tpl;
    using return_type = std::invoke_result_t<Fn>;

    // 2. Create the promise/future pair
    auto promise = std::make_shared<std::promise<return_type>>();
    auto ret_future = promise->get_future();

    // 3. Create a type-erased task for the queue
    std::packaged_task<void()> task([promise, func = std::move(func)] () mutable {
        try {
            promise->set_value(func());
        } catch (...) {
            promise->set_exception(std::current_exception());
        }
    });

    // 4. Submit the task and return the future
    exec.post(std::move(task));
    return ret_future;
}

This approach is more explicit than the shared_ptr<packaged_task> pattern. It directly demonstrates the principle: to get a future, you create a promise, and then you give that promise to the asynchronous worker so it can be fulfilled later. This is a powerful pattern to have in your toolbox for the thread pool project.

Conclusion

Today, we've gone far beyond simply using std::future and delved into its core mechanics. You now have a deep, first-principles understanding of how asynchronous results are communicated in C++.

Key Takeaways:

• std::promise and std::future communicate via a heap-allocated shared state (control block), which is managed by std::shared_ptr.
• This shared state uses a std::mutex, a std::condition_variable, and a ready flag to safely and efficiently synchronize the producer and consumer threads.
• The promise::set_value() method signals the completion, while future::get() blocks using cv.wait() until the result is ready.
• std::packaged_task is a convenient utility that wraps this promise/future mechanism for a given callable.
• There are multiple valid design patterns to integrate this mechanism into a thread pool, including both the shared_ptr<packaged_task> approach and the more explicit std::promise approach.

Next Lesson Preview:

Our thread pool is becoming quite robust, but it still has one significant flaw: if the pool is destroyed while tasks are still in the queue, that work is lost. In our next lesson, we will implement a graceful shutdown mechanism that ensures all pending tasks are completed before the worker threads are joined and the pool is destroyed.