Futures and promises

Suppose some computation has to run on a separate thread, and its answer has to come back to the code that started it. This is a common situation: the work happens in one place, and another part of the program needs the outcome. The question is how the answer gets from the thread that produced it to the code that is waiting for it.

Keep this question in mind as you read: when you have a task you want to run on a thread, how would you connect its outcome to a future that someone else can wait on? The rest of this article follows the path that packaged_task creates for that connection.

A future and a promise are a matched pair. The promise is the write side: the producing thread uses it to supply the result. The future is the read side: the consuming code uses it to wait for and retrieve that same result. Both handles refer to one result, so getting them to the correct parties, without mixing them up, is the setup work that needs to be done before the task can usefully run on a thread.

Because the two handles are connected, the code that holds the future does not need to know how the result was produced or where it was computed. It only needs to wait for the answer and retrieve it. The code that holds the promise is the one responsible for supplying the answer.

A packaged_task acts as a wrapper. You give it a task, and it supplies the surrounding code that takes whatever the task produces and places it into a promise. The source describes this as wrapper code that puts the return value or the exception from the task into its promise. The programmer does not have to hand-write the step that moves a finished result, or a thrown exception, into the promise. The packaged_task performs that step as part of running the task.

Notice that there are two possible outcomes the wrapper has to handle. A task can finish and produce a return value, or it can end by raising an exception. The packaged_task carries either outcome into the promise, so that whoever later reads the result through the future receives the same kind of answer the task itself produced.

The packaged_task holds the task, and it holds the promise. From the packaged_task, the caller can obtain the matching future. The thread runs the packaged_task, and that run is what eventually fills the promise. The diagram below shows which object holds a reference to which, so you can see where each piece sits.

The relationship is one of pairing. The packaged_task holds the promise, and get_future hands out the matching future. The future is the read side and the promise is the write side of the same result. The producer side and the consumer side never touch the same object directly: the task produces its outcome, the wrapper moves that outcome into the promise, and the future is the only handle the consumer uses.

When the task finishes on the worker thread, the wrapper checks which of two things happened. If the task returns normally, the return value goes into the promise. If the task ends by raising an exception, the exception goes into the promise instead. In both cases the promise is filled, so the future has something to deliver to the caller.

A packaged_task does not only run the work. It also gives you the other half of the connection. If you call its get_future operation, the packaged_task returns the future that corresponds to its promise. This is how the consuming side of the program receives a handle to the eventual result without touching the promise directly.

Read the sequence from top to bottom. The caller first asks the packaged_task for its future. The future is the handle the caller keeps. The task is then moved to a thread, which runs it. When the task finishes, the packaged_task fills the promise, and the caller can use the future it already holds to wait for and retrieve the answer.