Asynchronous Data Transfer with `std::promise` and `std::future`

1. The Core Problem: Getting a Result from Another Thread

Imagine you start a task on a new thread—perhaps a complex calculation or a network request. The main thread continues its own work but eventually needs the result of that background task. How does it get it?

You could implement this manually with a shared variable protected by a mutex and a condition variable to signal when the result is ready. However, this is boilerplate code that's easy to get wrong. C++ provides a much cleaner solution with the std::promise and std::future pair.

Conceptually, you can think of them as two ends of a communication channel:

• std::promise: The "writer" or "producer" end. The thread performing the calculation uses the promise to deliver the result.
• std::future: The "reader" or "consumer" end. The thread that needs the result holds the future and uses it to retrieve the value once it's available.

A great analogy from the Stack Overflow resource you'll see later is that of a microphone and a speaker. The std::promise is the microphone you give to the worker thread. The std::future is the speaker you keep, from which you'll eventually hear the result.

2. Under the Hood: The Shared State

The "wire" connecting the promise and future is a piece of memory on the heap, often called the shared state. This is the central mechanism that makes the whole system work. Your strong foundation in C and OS concepts will make understanding this straightforward.

The shared state typically contains:

1. The result value (or a place for it).
2. An exception pointer, in case the worker thread throws.
3. A "ready" flag to indicate whether the value/exception has been set.
4. A std::mutex and a std::condition_variable to synchronize access between the producer (promise) and consumer (future).

To see how these pieces fit together, let's watch a segment of a talk that builds this mechanism from scratch. This aligns perfectly with your preference for understanding things from first principles.

As you saw, the implementation is essentially a standardized, robust version of the manual synchronization pattern we discussed earlier. The promise calls notify_all() on the condition variable, and the future calls wait() on it.

3. Using the std::promise and std::future Pair

Now that you understand the internal mechanics, let's look at how to use the standard library versions.

The Producer Thread: Using std::promise

The thread that will produce the result holds the std::promise object.

1. Create a std::promise<T>, where T is the type of the result.
2. Get the associated std::future<T> by calling promise.get_future(). This future is then given to the consumer thread.
3. Move the std::promise into the producer thread. Promises, like many C++ concurrency objects, are move-only to enforce clear ownership semantics.
4. Once the result is ready, call promise.set_value(result).
5. If an error occurs, call promise.set_exception(std::current_exception()) to store the exception in the shared state.

The Consumer Thread: Using std::future

The thread that needs the result holds the std::future object.

1. To get the result, call future.get(). This call is blocking:
   • If the result is ready, it returns the value immediately.
   • If the result is not ready, it blocks the thread until the promise is fulfilled.
   • If the promise was fulfilled with set_exception(), future.get() will re-throw that exception in the consumer thread's context.
2. future.get() can only be called once on a given std::future object. After the call, the future becomes invalid. You can check this with the valid() member function.

The following document provides a concise summary of these concepts.

A Complete Example

Let's look at a sequence diagram that shows the entire workflow.

Here's how this looks in code:

#include <iostream>
#include <thread>
#include <future>
#include <chrono>

// The worker function that will run on a separate thread
void calculate_pi(std::promise<double> promise, int terms) {
    try {
        std::cout << "Worker thread: calculating Pi...\n";
        double sum = 0.0;
        for (int i = 0; i < terms; ++i) {
            int sign = (i % 2 == 0) ? 1 : -1;
            sum += sign / (2.0 * i + 1.0);
        }
        double pi = sum * 4.0;
        
        // Fulfill the promise with the calculated value
        promise.set_value(pi);

    } catch (...) {
        // If any exception occurs, store it in the promise
        promise.set_exception(std::current_exception());
    }
}

int main() {
    // 1. Create a promise for a double value
    std::promise<double> pi_promise;

    // 2. Get the future associated with the promise
    std::future<double> pi_future = pi_promise.get_future();

    // 3. Start the worker thread, moving the promise into it
    std::cout << "Main thread: starting worker...\n";
    std::thread worker(calculate_pi, std::move(pi_promise), 1000000);

    // Main thread can do other work here...
    std::cout << "Main thread: doing other work...\n";
    std::this_thread::sleep_for(std::chrono::milliseconds(500));

    // 4. Get the result from the future. This will block until the worker is done.
    try {
        std::cout << "Main thread: waiting for the result...\n";
        double pi = pi_future.get();
        std::cout << "Main thread: The calculated value of Pi is " << pi << std::endl;
    } catch (const std::exception& e) {
        std::cerr << "Main thread: Caught an exception from worker: " << e.what() << std::endl;
    }

    worker.join();
    return 0;
}

4. Advanced Topics: Shared Futures and Refactoring

What if multiple threads need to consume the same result? std::future is a single-consumer object. For this scenario, C++ provides std::shared_future. You can create one from a std::future using future.share(). A std::shared_future is copyable, and each copy can call get() to retrieve the result.

The following video shows a practical refactoring of a thread pool to use std::promise and std::future, and also touches on the difference between std::future and std::shared_future.

Conclusion

You have now learned the fundamental mechanism in modern C++ for transferring a single result from a producer thread to a consumer thread. This pattern is central to many asynchronous designs and is a key building block for the project you'll be developing.

Key Takeaways:

• Producer/Consumer Model: std::promise is for the producer thread to set a value or an exception. std::future is for the consumer thread to retrieve it.
• Shared State: They communicate via a hidden, synchronized shared state on the heap.
• Blocking get(): future.get() blocks until the result is ready and can only be called once.
• Exception Propagation: Exceptions thrown in the producer can be caught in the consumer by wrapping future.get() in a try...catch block. This is a powerful feature for error handling across threads.
• Ownership: std::promise and std::future are move-only. For multiple consumers, use the copyable std::shared_future.

What's Next?

While std::promise and std::future are powerful, they are still relatively low-level. Often, you don't want to manage the thread and promise manually. In the next lesson, we will explore std::packaged_task and std::async, two higher-level abstractions built directly on top of the promise/future mechanism that further simplify asynchronous programming.