Waiting for Threads with join

When a program starts one or more threads, it creates units of work that run alongside the rest of the program. Starting a thread does not, by itself, tell the program when that work is finished. If the program reaches its own end without any further coordination, it has no guarantee that its threads have completed. Managing threads means controlling this relationship, so that the program does not finish before the work it started is done.

This article uses one tool for that job: the join() method. Its purpose is to make sure a program does not exit until its threads have completed. Along the way we will look at the two ways a thread is given work to do, which are a function together with its arguments and a function object that carries its own data. We will also look at how join() changes the order in which things happen, and at the mistakes learners most often make about it.

A task that runs in a thread usually has work to do on some data. A thread that sums a list, sorts a collection, or updates a set of values needs access to that data. The basic idea is that a task needs data to work upon, and that data can be passed as arguments, either directly or as pointers or references to the data.

A thread can be given a function and its arguments, and the function then runs in a separate thread with those arguments. Consider the starting program's thread t1. It is created from a function, f, and an argument, ref(some_vec). When the thread starts, f runs in the new thread with that argument, so the effect is that f(some_vec) executes in the new thread. The same relationship applies to any thread built from a function and its arguments: the function is the work, and the arguments are the data it works on.

A function's parameter can be declared as a reference. The source gives the example vector<double>& v. The ampersand means that v is not a new copy of the vector; it names the caller's object. Because of this, a function with a reference parameter such as v works on the original data, not on a separate version of it.

The diagram shows the key point. There is one vector. The name some_vec in main and the name v in the function both lead to that same vector. When f works on v, it is working on the vector that main created, which is why the reference parameter matters when a thread is given the function.

The starting program defines a struct F. Its constructor takes a vector reference, and it stores that reference in its member v. This is how F carries data: the vector is held inside the object. The operator() member is declared on F, and the program states that F(vec2)() executes in a separate thread. In other words, the thread t2 is given a temporary F object built from vec2, and the thread calls that object's application operator.

Notice that the two threads in the program receive data in different forms. The thread t1 receives a function and a wrapped reference, while the thread t2 receives a function object that already holds its data. Both threads work on the data they were given, but the way that data reaches each thread differs.

The source states that std::ref is used to pass references to threads. In the starting program, the expression ref(some_vec) is how the first thread receives a reference to some_vec rather than the vector as a plain argument. The function f declares its parameter as a vector reference, so the reference that arrives in the thread refers to the same vector main created. The thread therefore operates on main's data.

The join() method ensures that a program does not exit until its threads have completed. The waiting is the whole purpose of the call. join() does not itself perform the thread's work, and it is not a way to start the thread. Its job is to hold the calling thread at that point until the joined thread finishes.

Follow the order of events between two parties: the main thread that calls join(), and the worker thread being joined. Read the sequence from top to bottom, since each step happens after the one above it.

The diagram shows the key point. The main thread reaches the join() call and waits. It does not continue past that point until the worker has terminated. Only after the worker terminates does the main thread resume, and only then can the program move on to whatever comes after the join.

The following example is an original illustration written for this article, not a listing from the source. It starts two worker threads and then calls join() on each of them before the main program prints its final message. The source does not present code for this, so the structure follows the standard Python threading interface, in which a thread is started and then joined. Each worker is given its function and its arguments through the args parameter.

Trace the program in order. Main creates the two thread objects and starts both. The two workers then run alongside each other, so the order in which their two messages appear is not guaranteed by this example. Main then reaches first.join() and waits for worker A to terminate. Once worker A has terminated, main reaches second.join() and waits for worker B. Only after both joins have finished does main print the completion message. What is guaranteed is the position of the final message relative to the joins, not the relative order of the two worker messages.