Skip to content
Tutorials Center
My learning

Topics

Lesson 92 of 135 ยท Advanced C

Multithreading

Learn multithreading in C with pthreads and C11 threads.h - create and join threads, fix race conditions with mutexes, use condition variables and atomics.

A thread is an independent path of execution inside a program. Every C program starts with one thread, the one that runs main. When you create more threads, they all run inside the same process and share the same global variables, heap and open files, but each one has its own stack and its own position in the code. On a machine with several CPU cores, threads really do run at the same time; on a single core, the operating system switches between them many times per second.

Threads let a program do several things at once: keep a user interface responsive while a file loads, serve many network clients, or split a big calculation across all cores. The price is that shared data must be protected. Two threads that touch the same variable without coordination cause a data race, which is undefined behavior. This lesson teaches the two thread APIs you'll meet in C: POSIX threads (pthreads), used on Linux, macOS and other Unix systems, and the standard C11 <threads.h>. You'll also learn mutexes, condition variables, atomics and the classic mistakes.

You should be comfortable with pointers, void pointers, structures and dynamic memory before you start.

Creating and joining a thread

With pthreads you include <pthread.h> and call pthread_create. It takes four arguments: a pointer to a pthread_t that receives the thread's ID, an attributes pointer (NULL for the defaults), the function the thread should run, and one void * argument for that function. The thread function must have exactly this shape:

C
void *thread_function(void *arg);

pthread_join waits until a thread finishes and collects the void * it returned. Every thread you create should be joined (or detached, see below); otherwise its resources are never released.

C Your first threads

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Here each thread is joined before the next one starts, so the output order is fixed. If you create both threads first and join them afterwards, they run concurrently and the two greetings may appear in either order. That's the first rule of threaded code: the order in which threads run is not under your control. Only synchronization (joins, mutexes, condition variables) creates a guaranteed order.

Unlike most C library functions, the pthread functions don't set errno. They return 0 on success and an error number (such as EAGAIN when the system can't create more threads) on failure. You can pass that number to strerror to get a message, as you learned in Error Handling.

Note: Our editor compiles with -pthread, which links the threading library. On your own machine, compile threaded programs with gcc -pthread main.c. Without it, older systems report "undefined reference to pthread_create".

Passing data in and getting results out

A thread function receives one void *. To give it several values, put them in a struct and pass a pointer to it. The struct must stay alive until the thread is done with it, so don't point at a local variable that goes out of scope while the thread runs. A common, safe pattern is an array of argument structs in main, one per thread, that outlives every join.

Results can travel back the same way: the thread writes into its own struct, and main reads the field after pthread_join. Because each thread writes only to its own struct, there's no sharing and no race.

C Splitting a sum across four threads

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

The output order is predictable because main prints only after joining each thread. Notice that &jobs[t] points at a different element for each thread. A classic bug is passing &t, the address of the loop counter itself: every thread then reads the same variable, which main keeps changing, so threads see wrong or duplicate values.

Race conditions

Now suppose all threads update one shared counter. counter++ looks like a single step, but the processor performs three: load the value, add one, store it back. If two threads load the same old value, both store the same new value, and one increment is lost.

C
static long counter = 0;           /* shared by all threads */

static void *count_up(void *arg)
{
    (void)arg;
    for (int i = 0; i < 100000; i++) {
        counter++;                 /* DATA RACE: undefined behavior */
    }
    return NULL;
}

With four threads you'd expect 400000, but on a multi-core machine this code typically prints a smaller number that changes from run to run. Formally it's worse than "a smaller number": an unsynchronized write that races with another access is undefined behavior, so the compiler is allowed to assume it never happens. Our sandbox runs on a single CPU, so the lost updates may not even appear there, which is exactly why races are so hard to find: code that passes every test can still be wrong.

The fix is to make sure only one thread at a time can run the read-modify-write. You have two tools: a mutex or an atomic variable.

Mutexes

A mutex (mutual exclusion lock) is a lock that only one thread can hold at a time. A thread calls pthread_mutex_lock before touching shared data and pthread_mutex_unlock afterwards. If another thread already holds the lock, lock waits until it's released. The code between lock and unlock is called the critical section.

C A mutex protects the shared counter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

PTHREAD_MUTEX_INITIALIZER sets up a statically allocated mutex. For a mutex inside a struct or on the heap, call pthread_mutex_init(&m, NULL) instead, and pthread_mutex_destroy when you're done.

Guidelines for using mutexes well:

  • Keep critical sections short. Do slow work (calculations, I/O) outside the lock and lock only to read or update shared state. In the example above, locking a million times is slow; a better design adds into a local variable and locks once at the end.
  • Every path must unlock. An early return or break inside the critical section that skips unlock leaves the mutex locked forever, and every other thread hangs.
  • One lock per piece of shared data, and document which lock protects what. A comment like /* protected by counter_lock */ next to the variable helps every future reader.

Deadlock

If thread A holds lock 1 and waits for lock 2 while thread B holds lock 2 and waits for lock 1, both wait forever. That's a deadlock. The standard cure is a lock order: decide once that lock 1 is always taken before lock 2, and follow that order everywhere. Locking a mutex you already hold is also a deadlock with the default mutex type, so don't call a function that locks from inside a critical section of the same lock.

Condition variables

A mutex stops threads from colliding, but sometimes a thread must wait for something to happen: a queue becomes non-empty, a job finishes, a flag changes. Checking in a loop ("busy waiting") wastes CPU. A condition variable lets a thread sleep until another thread signals that the state may have changed.

The pattern always has three parts: a piece of shared state, a mutex protecting it, and a condition variable. The waiting side looks like this:

C
pthread_mutex_lock(&lock);
while (!condition_is_true) {             /* always a loop, never a plain if */
    pthread_cond_wait(&changed, &lock);  /* unlocks, sleeps, relocks */
}
/* ... use the shared state ... */
pthread_mutex_unlock(&lock);

pthread_cond_wait atomically releases the mutex and goes to sleep; when it wakes, it takes the mutex again before returning. The while loop matters: wake-ups can be spurious (the thread wakes without a signal), and another thread may have changed the state again before this one got the lock back. The other side changes the state while holding the lock and then calls pthread_cond_signal (wake one waiter) or pthread_cond_broadcast (wake all).

Here is a complete producer-consumer program: a producer puts numbers into a small bounded buffer, a consumer takes them out, and each waits when the buffer is full or empty.

C Producer and consumer with a bounded buffer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

The consumer always prints 10, 20, ... 80 in order, because there's a single producer and a single consumer and the buffer is a FIFO circular queue. How the two threads interleave varies, but the buffer never holds more than three items and nobody spins in a busy loop. (For brevity this example skips the return-value checks on pthread_create; real code should keep them.)

C11 threads: <threads.h>

C11 added a portable thread API to the standard library. It mirrors pthreads closely, with shorter names:

pthreads C11 <threads.h>
pthread_t, pthread_create, pthread_join thrd_t, thrd_create, thrd_join
pthread_mutex_t, _lock, _unlock mtx_t, mtx_lock, mtx_unlock
pthread_cond_t, _wait, _signal, _broadcast cnd_t, cnd_wait, cnd_signal, cnd_broadcast
returns 0 or an error number returns thrd_success, thrd_error, thrd_nomem, โ€ฆ

The thread function returns int instead of void *, and there is no static initializer for mutexes: you call mtx_init(&m, mtx_plain). Support was patchy for years: glibc added it in version 2.28 (2018), and Microsoft's C runtime only in Visual Studio 2022 17.8. Code that must build on older systems still uses pthreads (or Windows threads). Our compiler supports it:

C The same counter with C11 threads

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

<threads.h> also provides thrd_sleep, thrd_yield, call_once (run an initializer exactly once, however many threads call it) and thread-specific storage with tss_create. If __STDC_NO_THREADS__ is defined, the implementation doesn't offer the header at all; see Conditional Compilation for testing such macros.

Atomics: <stdatomic.h>

For a single counter or flag, a mutex is heavyweight. C11's <stdatomic.h> provides atomic types whose operations can't be torn apart by other threads. atomic_fetch_add(&x, 1) performs the load-add-store as one indivisible step, and even plain x++ on an atomic_int is atomic.

C An atomic counter needs no lock

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

The plain functions (atomic_load, atomic_store, atomic_fetch_add) use the strongest ordering, memory_order_seq_cst, which behaves the way you intuitively expect. The _explicit versions take a weaker memory order. memory_order_relaxed is fine for a pure counter whose final value you read after joining, because you don't use it to publish other data. When one thread sets a flag to say "the data is ready", the writer uses memory_order_release and the reader memory_order_acquire, so the data written before the flag is guaranteed to be visible after it. If you're not sure, use the default functions.

Other useful operations are atomic_exchange (swap in a new value), atomic_compare_exchange_strong (change the value only if it still equals what you expect, the building block of lock-free algorithms) and atomic_flag (a guaranteed lock-free boolean). Atomics are great for counters and flags; for anything involving several variables that must change together, use a mutex.

Warning: volatile does not make a variable thread-safe. It only stops the compiler from optimizing away accesses (it was designed for hardware registers). Two threads incrementing a volatile int still race. Use _Atomic/atomic_int or a mutex.

Thread-local storage

Sometimes each thread needs its own copy of a global-looking variable, such as a per-thread buffer or error code. C11 added the _Thread_local storage class; C23 made thread_local a keyword (before C23 it was a macro in <threads.h>). The C library's own errno is thread-local, so one thread's failed call never overwrites another thread's errno.

C
thread_local int calls_in_this_thread = 0;   /* C23; use _Thread_local in C11 */

Cancelling a thread, and who am I?

Sometimes one thread has to stop another before it finishes: a search that the user abandoned, a worker pool shutting down. POSIX offers pthread_cancel(thread), which requests that the thread end. The request is not a kill switch:

  • The target thread acts on it only at a cancellation point, a call that is allowed to block or to wait, such as sleep, nanosleep, read, write, pthread_cond_wait, pthread_join and pthread_testcancel. A thread in a tight loop of pure arithmetic is never cancelled unless it calls pthread_testcancel() now and then.
  • When the request is acted on, the thread runs its cleanup handlers and then exits as if it had called pthread_exit(PTHREAD_CANCELED). A joiner sees that special value as the result.
  • A thread can turn cancellation off for a stretch with pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, &old), which is how you protect a short critical section, and back on with PTHREAD_CANCEL_ENABLE. The default type is deferred, meaning "only at cancellation points"; asynchronous cancellation (pthread_setcanceltype) can strike at any instruction and is almost never safe, since the thread might die holding a lock or halfway through malloc.

Cleanup handlers are how a cancelled thread releases what it owns. pthread_cleanup_push(fn, arg) registers a function, and pthread_cleanup_pop(execute) removes it again, running it first if execute is nonzero. Both are macros that must appear as a matched pair in the same block of the same function.

pthread_self() returns the calling thread's own ID, and pthread_equal(a, b) compares two IDs. Compare pthread_t values with pthread_equal, never with ==: the type is opaque and may be a struct on some systems.

C Cancelling a worker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

The worker prints a few steps, main cancels it during a nanosleep, the cleanup handler frees the buffer, and pthread_join reports PTHREAD_CANCELED. The exact number of steps depends on timing, but cleanup always runs once.

Prefer a cooperative design when you can: a shared flag (an atomic or a mutex-protected variable) that the worker checks at safe points, so it finishes its current unit of work and cleans up in plain code. Cancellation is the right tool when the thread is stuck in a blocking call you cannot interrupt another way, and when you have carefully registered cleanup handlers. C11 <threads.h> has no cancellation at all, so portable code uses flags.

Detached threads and other lifecycle details

  • Joining or detaching. pthread_detach(t) tells the system to clean up the thread automatically when it ends; you can't join it afterwards. Use it for fire-and-forget work, but remember a detached thread is killed when main returns, because returning from main ends the whole process.
  • pthread_exit ends the calling thread. Called from main, it ends only the main thread and lets the others keep running.
  • Thread-safe functions. Some older library functions keep hidden static state and are not safe to call from several threads, for example strtok, localtime and rand. Use their reentrant versions (strtok_r, localtime_r) or give each thread its own state, as covered in String Functions and Time and Date.
  • printf from threads is safe (each call is atomic with respect to other printf calls), but lines from different threads interleave in an unpredictable order.

Why threads, and what goes wrong

Advantages. Threads let one program use several CPU cores at once, keep a program responsive while one thread waits for a disk or network, and share data cheaply because all threads live in the same address space. Creating a thread is also much cheaper than starting a process.

Disadvantages. That shared memory is the danger: data races, deadlocks and bugs that appear only under certain timings and vanish when you add a printf. A crash in one thread (a bad pointer) takes down the whole process, and debugging is harder because runs are not repeatable.

Starvation. Deadlock is not the only liveness problem. A thread is starved when it is ready to run but never gets the resource it needs, for example because other threads keep grabbing a mutex the moment it is released, or because high-priority threads always run first. The program does not hang, but one thread makes little or no progress. Typical cures: hold locks for as short a time as possible, do not take a lock inside a tight loop that immediately takes it again, use queues or condition variables so waiting threads are woken in a fair order, and avoid giving threads different priorities unless you must. Starvation, like deadlock, is a design problem that only shows up under load, so reason about it before it happens.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Four threads each run counter++ 1000 times on a shared plain int with no lock. What can you say about the final value?

    The read-modify-write steps can interleave and lose updates, and formally a data race is undefined behavior. A mutex or an atomic counter makes the result 4000.
  2. 2. Why is pthread_cond_wait always called inside a while loop?

    The loop rechecks the condition after every wake-up, so the thread only continues when the condition is really true.
  3. 3. A loop calls pthread_create(&threads[i], NULL, work, &i) for i = 0..3. What is wrong?

    Pass a pointer to a separate value per thread, such as &ids[i], that lives until the thread is done with it.
  4. 4. Thread A locks m1 then m2; thread B locks m2 then m1. What can happen?

    Always taking locks in one agreed order prevents this kind of deadlock.
  5. 5. Which declaration makes a counter safe to increment from many threads without a mutex?

    Operations on atomic types are indivisible. volatile only stops optimizations and gives no thread safety.

Summary

  • Threads share globals, the heap and files but each has its own stack; their execution order is not under your control.
  • pthreads: pthread_create starts a thread running void *f(void *), pthread_join waits for it. Functions return 0 or an error number, not errno.
  • Pass each thread its own argument struct that outlives the thread; read results after joining.
  • Unsynchronized access to shared data is a data race and undefined behavior. Protect it with a mutex (short critical sections, unlock on every path, a fixed lock order to avoid deadlock).
  • Condition variables let threads sleep until shared state changes; always wait in a while loop.
  • C11 <threads.h> (thrd_create, mtx_t, cnd_t) is the standard API; pthreads remain more widely available.
  • <stdatomic.h> makes single counters and flags safe without locks; volatile does not.
  • thread_local (C23, _Thread_local in C11) gives each thread its own copy of a variable.

Next: Signals and Signal Handling.