Robust Threading with Error Handling

The Pthreads Error Handling Model

In many standard C functions, errors are reported by returning a special value (like -1 or NULL) and setting a global integer variable named errno. You then use functions like perror() to print a descriptive message based on errno's value.

The Pthreads library follows a different convention. On failure, most pthread_* functions do not set errno. Instead, they directly return a positive error number. A return value of 0 indicates success.

This means the common pattern of if (function() == -1) { perror("..."); } will not work correctly. You must capture the integer return value and check if it's non-zero.

Let's see the basic implementation of this check.

This simple if (result != 0) check is the absolute minimum, but we can do much better. The integer returned by a failed Pthreads function is the error code itself (e.g., EAGAIN, EINVAL). To create useful error messages, we can pass this code to the strerror() function, which converts the error number into a human-readable string.

Robust Thread Creation with pthread_create

Let's build a truly robust thread creation mechanism. We will use the official Linux manual page for pthread_create, as it contains a perfect example of production-quality error handling.

Dissecting the handle_error_en Macro

The example program from the man page is excellent. Let's break down its error-handling macro:

#define handle_error_en(en, msg) \
    do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)

This is a clever and robust way to handle Pthreads errors. Here's what it does:

1. errno = en;: It takes the error number en returned by the pthread_* function and manually assigns it to the global errno variable.
2. perror(msg);: Now that errno is set correctly, it calls perror(). perror prints your custom message (msg), followed by a colon, and then the descriptive error string corresponding to the current value of errno.
3. exit(EXIT_FAILURE);: It terminates the program. In many cases, if a critical resource like a thread cannot be created, the application cannot safely continue.

The do { ... } while (0) wrapper is a standard C idiom to ensure the macro behaves like a single statement, which is important when it's used inside an if block without curly braces.

Here is how it's used in practice:

// s will hold the return value from the pthread function
int s; 

// ...

s = pthread_create(&tinfo[tnum].thread_id, &attr, &thread_start, &tinfo[tnum]);
if (s != 0)
    handle_error_en(s, "pthread_create");

This pattern is clean, informative, and reliable.

Robust Mutex Initialization

The same error-handling principle applies to creating other synchronization primitives, like mutexes. Before you can lock a mutex, you must initialize it.

Just like pthread_create, pthread_mutex_init returns 0 on success and a positive error number on failure. Failures can happen due to insufficient memory or if the attributes pointer (attr) is invalid. We can—and should—apply the same error-checking pattern.

#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>

#define handle_error_en(en, msg) \
    do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
    
// ...

pthread_mutex_t my_mutex;
int s = pthread_mutex_init(&my_mutex, NULL);
if (s != 0) {
    handle_error_en(s, "pthread_mutex_init");
}

// ... use the mutex ...

s = pthread_mutex_destroy(&my_mutex);
if (s != 0) {
    handle_error_en(s, "pthread_mutex_destroy");
}

Notice we also check the return value of pthread_mutex_destroy. It's good practice to check the return code of every Pthreads function.

Alternative: Static Initialization

For mutexes that are declared globally or with static storage duration, Pthreads provides a simpler initialization method that cannot fail at runtime.

The static initializer looks like this:

pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;

When to use which method?

• PTHREAD_MUTEX_INITIALIZER (Static):
  • Pros: Simple, requires no error checking. The initialization is handled by the compiler and loader.
  • Cons: Can only be used for mutexes with static storage duration (e.g., global variables). You cannot use it to initialize a mutex that you allocate dynamically on the heap (e.g., inside a struct you've malloc'd). You also cannot specify any custom mutex attributes.
• pthread_mutex_init() (Dynamic):
  • Pros: Flexible. It can initialize any mutex, including those on the heap. It allows you to specify custom attributes for advanced behavior (which we will see later).
  • Cons: It's a runtime function that can fail, so you must check its return value.

For your goal of building complex, dynamic data structures, you will frequently be using pthread_mutex_init() for mutexes embedded within heap-allocated objects.

struct safe_list {
    struct node* head;
    pthread_mutex_t mutex;
};

struct safe_list* create_list() {
    struct safe_list* lst = malloc(sizeof(struct safe_list));
    if (lst == NULL) {
        // handle malloc failure
        return NULL;
    }
    
    // TODO: Initialize the mutex inside the 'lst' struct.
    
    lst->head = NULL;
    return lst;
}

struct safe_list* create_list() {
    struct safe_list* lst = malloc(sizeof(struct safe_list));
    if (lst == NULL) {
        perror("malloc");
        return NULL;
    }
    
    // Initialize the mutex inside the 'lst' struct.
    int s = pthread_mutex_init(&lst->mutex, NULL);
    if (s != 0) {
        // Clean up allocated memory before exiting
        free(lst); 
        errno = s; // Set errno from the pthread return value
        perror("pthread_mutex_init");
        return NULL;
    }
    
    lst->head = NULL;
    return lst;
}

Conclusion

You've now moved beyond basic thread programming into the realm of robust, production-ready implementation. Building reliable concurrent systems starts with a solid foundation, and that foundation is comprehensive error checking.

Key Takeaways:

• Pthreads functions like pthread_create and pthread_mutex_init return 0 on success and a positive error number on failure.
• They do not set the global errno variable directly. You must capture the return value to handle errors.
• A robust error-handling pattern involves assigning the returned error number to errno and then using perror() for a descriptive message.
• Always check the return values of functions that create or destroy Pthreads objects.
• For statically allocated mutexes, PTHREAD_MUTEX_INITIALIZER offers a simple, non-failing alternative to pthread_mutex_init().

Preview of the Next Lesson:
We now know how to create threads and initialize mutexes in a robust manner. The next logical step is to use that mutex to do its job: protecting shared data. In the next lesson, we will cover how to protect critical sections and enforce mutual exclusion using pthread_mutex_lock and pthread_mutex_unlock, which is the core of mutex-based synchronization.