§27.1–27.2Thread Creation … Thread Completion

Threads exist; now, the levers. This chapter is the reference card — the concepts arrive slowly (with many examples) in the chapters that follow.

27.1 Thread Creation

In POSIX, one call:

#include <pthread.h>
int
pthread_create(pthread_t      *thread,
         const pthread_attr_t *attr,
               void           *(*start_routine)(void*),
               void           *arg);

The declaration looks complex (function pointers, if you haven’t met them, take a breath) but decomposes cleanly:

Packing arguments, the standard way (Figure 27.1):

typedef struct { int a; int b; } myarg_t;

void *mythread(void *arg) {
    myarg_t *args = (myarg_t *) arg;
    printf("%d %d\n", args->a, args->b);
    return NULL;
}

int main(int argc, char *argv[]) {
    pthread_t p;
    myarg_t args = { 10, 20 };
    int rc = pthread_create(&p, NULL, mythread, &args);
    ...
}

And there it is: another live executing entity, with its own call stack, in the same address space as every other thread in the program. The fun thus begins!

27.2 Thread Completion

To wait for a thread, join join pthread_join(thread, &retval): block until the named thread completes, optionally collecting its void* return value. Long-lived servers may never join; parallel task programs join to know the work is done. (create-then-immediately-join has a simpler name: a procedure call.) defined in ch. 27 — open in glossary it:

int pthread_join(pthread_t thread, void **value_ptr);

The first argument names the thread (the handle create initialized); the second is a pointer to your void* — join writes the thread’s return value through it (pass NULL if you don’t care). The full round-trip (Figure 27.2):

typedef struct { int a; int b; } myarg_t;
typedef struct { int x; int y; } myret_t;

void *mythread(void *arg) {
    myret_t *rvals = Malloc(sizeof(myret_t));
    rvals->x = 1;
    rvals->y = 2;
    return (void *) rvals;
}

int main(int argc, char *argv[]) {
    pthread_t p;
    myret_t *rvals;
    myarg_t args = { 10, 20 };
    Pthread_create(&p, NULL, mythread, &args);
    Pthread_join(p, (void **) &rvals);
    printf("returned %d %d\n", rvals->x, rvals->y);
    free(rvals);
    return 0;
}

(Those capitalized Pthread_* calls are assert-on-failure wrappers — a convention worth copying.) For single word-sized values, skip the structs and cast straight through the pointer (Figure 27.3):

void *mythread(void *arg) {
    long long int value = (long long int) arg;
    printf("%lld\n", value);
    return (void *) (value + 1);
}

One danger deserves its own walkthrough — returning a pointer to the thread’s own stack:

Finally, two structural notes. Creating a thread and immediately joining it is a pretty strange way to create a thread — there’s an easier way to accomplish that exact task, called a procedure call. And not all threaded code joins at all: a web server’s main thread may dispatch to workers indefinitely, while a parallel program joins at each stage boundary to know the work is done before moving on.