Introduction

On Linux, you can bind a specific POSIX thread to one CPU or a set of CPUs by using pthread_setaffinity_np. This is a thread-level scheduling hint to the kernel, and it is mostly useful for performance tuning, latency experiments, or workloads that benefit from cache locality. The main thing to remember is that affinity is a Linux-specific extension, not portable POSIX behavior.

The Core API

The usual pattern is:

• create or identify the target thread
• build a cpu_set_t
• clear it with CPU_ZERO
• add one or more CPU indexes with CPU_SET
• call pthread_setaffinity_np

1#define _GNU_SOURCE
2#include <pthread.h>
3#include <sched.h>
4#include <stdio.h>
5#include <stdlib.h>
6#include <unistd.h>
7
8void *worker(void *arg) {
9    cpu_set_t set;
10    CPU_ZERO(&set);
11
12    if (pthread_getaffinity_np(pthread_self(), sizeof(cpu_set_t), &set) != 0) {
13        perror("pthread_getaffinity_np");
14        return NULL;
15    }
16
17    for (int cpu = 0; cpu < CPU_SETSIZE; cpu++) {
18        if (CPU_ISSET(cpu, &set)) {
19            printf("thread can run on CPU %d\n", cpu);
20        }
21    }
22
23    return NULL;
24}
25
26int main(void) {
27    pthread_t thread;
28    cpu_set_t set;
29
30    if (pthread_create(&thread, NULL, worker, NULL) != 0) {
31        perror("pthread_create");
32        return 1;
33    }
34
35    CPU_ZERO(&set);
36    CPU_SET(0, &set);
37
38    if (pthread_setaffinity_np(thread, sizeof(cpu_set_t), &set) != 0) {
39        perror("pthread_setaffinity_np");
40        return 1;
41    }
42
43    pthread_join(thread, NULL);
44    return 0;
45}

This requests that the thread run only on CPU 0.

Affinity Can Be a CPU Set, Not Just One Core

You do not have to pin a thread to a single CPU. You can allow a subset.

1CPU_ZERO(&set);
2CPU_SET(1, &set);
3CPU_SET(3, &set);
4pthread_setaffinity_np(thread, sizeof(cpu_set_t), &set);

That tells the scheduler the thread may run on CPU 1 or 3, but not on the others.

Use pthread_self() for the Current Thread

If a thread wants to set its own affinity, it can use pthread_self().

pthread_t self = pthread_self();
pthread_setaffinity_np(self, sizeof(cpu_set_t), &set);

This is often simpler when the worker thread knows how it should be pinned.

Check the Result With pthread_getaffinity_np

Do not assume the setting succeeded silently. Query it back.

cpu_set_t current;
CPU_ZERO(&current);
pthread_getaffinity_np(thread, sizeof(cpu_set_t), &current);

This matters because affinity requests can fail for permission reasons, invalid CPU indexes, or because the requested CPU set is incompatible with cgroup or container restrictions.

Affinity Is a Hint With Real Tradeoffs

Pinning threads can help when:

• you want better cache locality
• you are measuring deterministic latency
• you are isolating noisy workloads
• you are tuning a high-performance system

It can hurt when:

• the machine is already lightly loaded and the scheduler could do better on its own
• you over-constrain threads and create imbalance
• the application runs inside containers or cgroups with limited CPU visibility

So affinity is a tuning tool, not a default optimization.

It is also worth remembering that affinity does not bypass the kernel scheduler entirely. The scheduler still decides when the thread runs; affinity only narrows where it is allowed to run. That is why the feature is best understood as a constraint on scheduling, not total manual control.

Compile With -pthread

Because this is pthread code, compile it correctly.

gcc -O2 -pthread affinity.c -o affinity

Omitting -pthread is a common reason for confusing build or runtime behavior.

Common Pitfalls

• Forgetting that pthread_setaffinity_np is Linux-specific and non-portable.
• Setting an invalid CPU index.
• Pinning too aggressively and making the workload less balanced.
• Assuming affinity guarantees exclusive use of a CPU.
• Failing to verify the active affinity mask after the call.

Summary

• Use pthread_setaffinity_np with a cpu_set_t to set thread affinity on Linux.
• Build the allowed CPU mask with CPU_ZERO and CPU_SET.
• Use pthread_self() for the current thread or a pthread_t handle for another thread.
• Verify the result with pthread_getaffinity_np.
• Affinity can help specific workloads, but it is a targeted tuning technique, not a universal speed boost.