Threads & Concurrency

/* Task parallelism — threads do DIFFERENT things */
/* Thread A sorts the left half of an array         */
/* Thread B finds the minimum in the right half     */
/* → The operation varies per thread                */

/* Data parallelism — threads do the SAME thing on different data */
/* 8 threads each sum 1/8 of an array (parallel reduction)       */
/* → Same function, different data slice                          */

/*  Example dependency graph:                                         */
/*                                                                    */
/*          [Parse file]                                              */
/*          /           \                                             */
/*   [Process A]    [Process B]    ← no dependency: run in parallel  */
/*          \           /                                             */
/*          [Merge results]                                           */
/*          |                                                         */
/*        [Write output]                                              */
/*                                                                    */
/* Critical path = Parse + max(A,B) + Merge + Write                  */
/* Max parallelism at step 2 = 2 threads (limited by independent tasks) */

/* Parallelizing two independent tasks from the graph above */
pthread_t t_a, t_b;

pthread_create(&t_a, NULL, process_a, data);  /* start A */
pthread_create(&t_b, NULL, process_b, data);  /* start B simultaneously */

pthread_join(t_a, NULL);  /* wait for A to finish */
pthread_join(t_b, NULL);  /* wait for B to finish */
/* Now both A and B are done — safe to call merge_results() */
merge_results();

/* Every thread function MUST have this exact signature */
void* my_thread_func(void* arg) {
 ^      ^                 ^
 |      |                 └── single argument: always void* (cast to your type inside)
 |      └─────────────────── return type: always void* (cast your return value, or NULL)
 └────────────────────────── your function name (any valid identifier)
    /* ... your thread's work here ... */
    return NULL;  /* return NULL when done (or cast a value to void*) */
}

/* Signature from <pthread.h> */
int pthread_create(
    pthread_t  *tid,                     /* arg 1 */
    const pthread_attr_t *attr,           /* arg 2 */
    void* (*start_routine)(void*),      /* arg 3 */
    void* arg                             /* arg 4 */
);
 ^
 └── returns 0 on success, non-zero error code on failure

/* Argument breakdown: */
/* arg 1 — tid: address of a pthread_t variable to store the new thread's ID */
/*   → You pass &mythread so pthreads can write the ID back to you          */
/* arg 2 — attr: thread attributes (stack size, detach state, etc.)          */
/*   → Pass NULL to use sensible defaults (joinable, default stack size)     */
/* arg 3 — start_routine: function pointer — the work the thread will do     */
/*   → Must match signature: void* fn(void*)                                 */
/* arg 4 — arg: a single void* argument passed to start_routine at runtime   */
/*   → Pass NULL if you have no argument; cast your pointer to (void*)       */

/* Example usage: */
pthread_t tid;
int rc = pthread_create(&tid, NULL, my_thread_func, NULL);
if (rc != 0) { perror("pthread_create"); exit(1); }

/* Signature from <pthread.h> */
int pthread_join(
    pthread_t   tid,     /* arg 1: thread ID to wait for (the VALUE, not a pointer) */
    void**      status   /* arg 2: where to store the thread's return value, or NULL */
);
 ^
 └── returns 0 on success

/* pthread_join BLOCKS until the named thread terminates.            */
/* Once joined, the thread no longer exists. Do not join twice.      */

/* Example: wait for tid and ignore return value */
pthread_join(tid, NULL);

/* Example: capture the return value from the thread */
void* retval;
pthread_join(tid, &retval);
/* retval now holds whatever the thread returned with return or pthread_exit */

/* Three ways a thread can terminate: */

/* 1. Return from the thread function (preferred) */
void* worker(void* arg) {
    /* ... work ... */
    return NULL;          /* thread ends cleanly */
}

/* 2. Call pthread_exit() explicitly (useful deep in a call chain) */
pthread_exit(NULL);   /* only THIS thread terminates, others continue */

/* 3. Be cancelled by another thread with pthread_cancel(tid) */

/* CRITICAL DISTINCTION: */
/* exit()           kills the ENTIRE process (all threads die!) */
/* pthread_exit()   kills ONLY the calling thread               */
/* return in main() also kills all threads (like exit())        */
/* → if main() returns before threads finish, threads are killed */
/* → fix: call pthread_join() before returning from main()      */

/* SAFE: use a separate variable per thread (array of args) */
int args[4];
pthread_t tids[4];
for (int i = 0; i < 4; i++) {
    args[i] = i;                                        /* unique value per thread */
    pthread_create(&tids[i], NULL, worker, (void*)&args[i]);
}

/* UNSAFE (race condition!): passing &i directly */
/* pthread_create(&tids[i], NULL, worker, (void*)&i); // BUG! */
/* By the time the thread reads *arg, i has already been incremented! */

/* Inside the thread function — cast back to original type: */
void* worker(void* arg) {
    int my_id = *(int*)arg;   /* cast void* back to int*, then dereference */
    printf("I am thread %d\n", my_id);
    return NULL;
}