Pthread Mutex: The POSIX… — Mutex Locks: Mutual… | OneNoughtOne

0/105

Operating SystemsMutex Locks

Mutex Locks: Mutual Exclusion Primitives

LevelIntermediate

Duration60 mins

TopicMutex Locks

4 / 5

Pthread Mutex: The POSIX Standard API

The Industry Standard

Having understood mutex concepts and implementation, we now turn to the practical API that millions of developers use daily: POSIX threads (pthreads) . The pthread mutex API is the standard interface for mutex synchronization on Linux, macOS, BSD, and virtually every Unix-like operating system. Mastering pthread mutexes is essential for any systems programmer. Whether you're building servers, databases, operating systems, or high-performance applications, you will encounter pthreads. Understanding not just what the API does, but why it's designed this way, will make you a more effective engineer.

What You Will Learn

By the end of this page, you will master the pthread_mutex API: initialization options, attribute configuration, type selection, operation semantics, error handling, and production best practices. You will understand the tradeoffs between different mutex types and know how to avoid common pitfalls.

The pthread_mutex_t Type

The core of the pthread mutex API is the pthread_mutex_t type—an opaque data structure representing a mutex. Key Characteristics: Opaque structure: You cannot access or manipulate its internal fields directly. It must be used only through pthread_mutex_* functions. Fixed size: The size is ABI-defined and constant on a given platform (though it varies between OSes). Not copyable: You cannot simply copy a mutex with = . Two mutexes must be separately initialized. Initialization required: A mutex must be initialized before use, either statically or dynamically.

pthread_mutex_basics.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
#include <pthread.h>
#include <stdio.h>
 
// ─── METHOD 1: STATIC INITIALIZATION ──────────────────────
// Use when mutex is a global or static variable
// No cleanup needed (but pthread_mutex_destroy is still safe to call)
 
static pthread_mutex_t global_lock = PTHREAD_MUTEX_INITIALIZER;
 
// ─── METHOD 2: DYNAMIC INITIALIZATION ─────────────────────
// Use when mutex is allocated dynamically or needs custom attributes
// Must call pthread_mutex_destroy when done
 
void dynamic_example(void) {
    pthread_mutex_t* dynamic_lock = malloc(sizeof(pthread_mutex_t));
    
    // Initialize with default attributes (NULL)
    int result = pthread_mutex_init(dynamic_lock, NULL);
    if (result != 0) {
        fprintf(stderr, "Mutex init failed: %d
", result);
        exit(1);
    }
    
    // ... use the mutex ...
    
    // Clean up when done
    pthread_mutex_destroy(dynamic_lock);
    free(dynamic_lock);
}
 
// ─── CRITICAL POINTS ──────────────────────────────────────
// 
// 1. PTHREAD_MUTEX_INITIALIZER is a MACRO that expands to a
//    brace-enclosed initializer. It can ONLY be used at declaration.
//
// 2. You cannot use PTHREAD_MUTEX_INITIALIZER for assignment:
//    pthread_mutex_t m;
//    m = PTHREAD_MUTEX_INITIALIZER;  // WRONG! Compile error.
//
// 3. For non-default attributes, you MUST use pthread_mutex_init.
//
// 4. pthread_mutex_destroy releases any resources. After destroy,
//    the mutex is in an undefined state until reinitialized.

When to Use Static vs Dynamic Initialization

Static: Use PTHREAD_MUTEX_INITIALIZER for global/static mutexes with default attributes. It's simpler and slightly faster (no function call). Dynamic: Use pthread_mutex_init when you need custom attributes (error-checking, recursive), when the mutex is heap-allocated, or when initializing an array of mutexes.

Mutex Attributes (pthread_mutexattr_t)

Mutex behavior can be customized through attributes . The pthread_mutexattr_t type holds configuration options that are passed to pthread_mutex_init . Available Attributes:

Pthread Mutex Attributes
Attribute	Function	Purpose
Type	`pthread_mutexattr_settype()`	Normal, error-checking, recursive, or default behavior
Protocol	`pthread_mutexattr_setprotocol()`	Priority inheritance, priority ceiling, or none
Priority Ceiling	`pthread_mutexattr_setprioceiling()`	Maximum priority when using ceiling protocol
Process-Shared	`pthread_mutexattr_setpshared()`	Can mutex be shared between processes?
Robust	`pthread_mutexattr_setrobust()`	Behavior when owner terminates holding lock

mutex_attributes.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
#include <pthread.h>
 
// Creating a mutex with custom attributes
 
int create_recursive_mutex(pthread_mutex_t* mutex) {
    pthread_mutexattr_t attr;
    int result;
    
    // Step 1: Initialize the attribute object
    result = pthread_mutexattr_init(&attr);
    if (result != 0) return result;
    
    // Step 2: Configure desired attributes
    result = pthread_mutexattr_settype(&attr, PTHREAD_MUTEX_RECURSIVE);
    if (result != 0) {
        pthread_mutexattr_destroy(&attr);
        return result;
    }
    
    // Step 3: Create the mutex with these attributes
    result = pthread_mutex_init(mutex, &attr);
    
    // Step 4: Clean up the attribute object (mutex keeps its settings)
    pthread_mutexattr_destroy(&attr);
    
    return result;
}
 
// Creating an error-checking mutex
int create_errorcheck_mutex(pthread_mutex_t* mutex) {
    pthread_mutexattr_t attr;
    pthread_mutexattr_init(&attr);
    pthread_mutexattr_settype(&attr, PTHREAD_MUTEX_ERRORCHECK);
    int result = pthread_mutex_init(mutex, &attr);
    pthread_mutexattr_destroy(&attr);
    return result;
}
 
// Creating a process-shared mutex (for shared memory between processes)
int create_shared_mutex(pthread_mutex_t* mutex) {
    pthread_mutexattr_t attr;
    pthread_mutexattr_init(&attr);
    pthread_mutexattr_setpshared(&attr, PTHREAD_PROCESS_SHARED);
    int result = pthread_mutex_init(mutex, &attr);
    pthread_mutexattr_destroy(&attr);
    return result;
}

Attribute Object Lifecycle

The pthread_mutexattr_t object is only used during pthread_mutex_init. After initialization, the mutex has its own copy of the settings. You can destroy the attribute object immediately after init, or reuse it to create multiple mutexes with the same settings.

Mutex Types: Behavior Variants

POSIX defines four mutex types, each with different behavior for edge cases like relocking by the same thread or unlocking by a different thread.

POSIX Mutex Types Comparison
Type	Relock by Owner	Unlock by Non-Owner	Unlock when Unlocked	Use Case
PTHREAD_MUTEX_NORMAL	Deadlock	Undefined	Undefined	Performance-critical, trusted code
PTHREAD_MUTEX_ERRORCHECK	Returns EDEADLK	Returns EPERM	Returns EPERM	Development, debugging
PTHREAD_MUTEX_RECURSIVE	Succeeds (count++)	Returns EPERM	Returns EPERM	Reentrant code, callbacks
PTHREAD_MUTEX_DEFAULT	Undefined	Undefined	Undefined	Implementation-defined (often = NORMAL)

mutex_types_examples.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
#include <pthread.h>
#include <stdio.h>
#include <errno.h>
 
// ═══════════════════════════════════════════════════════════
// NORMAL MUTEX
// ═══════════════════════════════════════════════════════════
// - Fastest (minimal checking)
// - Undefined behavior on misuse (deadlock, corruption, etc.)
// - Use when you are 100% confident in correct usage
 
pthread_mutex_t normal_mutex = PTHREAD_MUTEX_INITIALIZER;
 
void normal_example(void) {
    pthread_mutex_lock(&normal_mutex);
    
    // BUG: Attempting to lock again causes DEADLOCK
    // pthread_mutex_lock(&normal_mutex);  // Hangs forever!
    
    pthread_mutex_unlock(&normal_mutex);
}
 
// ═══════════════════════════════════════════════════════════
// ERROR-CHECKING MUTEX  
// ═══════════════════════════════════════════════════════════
// - Detects common errors (double lock, wrong unlock)
// - Returns error codes instead of undefined behavior
// - Slight overhead from additional checks
 
void errorcheck_example(void) {
    pthread_mutex_t mutex;
    pthread_mutexattr_t attr;
    
    pthread_mutexattr_init(&attr);
    pthread_mutexattr_settype(&attr, PTHREAD_MUTEX_ERRORCHECK);
    pthread_mutex_init(&mutex, &attr);
    pthread_mutexattr_destroy(&attr);
    
    pthread_mutex_lock(&mutex);
    
    // Attempt to lock again - returns EDEADLK instead of deadlocking
    int result = pthread_mutex_lock(&mutex);
    if (result == EDEADLK) {
        printf("Error: Detected attempt to relock owned mutex!
");
    }
    
    pthread_mutex_unlock(&mutex);
    
    // Attempt to unlock when not locked - returns EPERM
    result = pthread_mutex_unlock(&mutex);
    if (result == EPERM) {
        printf("Error: Detected attempt to unlock non-owned mutex!
");
    }
    
    pthread_mutex_destroy(&mutex);
}
 
// ═══════════════════════════════════════════════════════════
// RECURSIVE MUTEX
// ═══════════════════════════════════════════════════════════
// - Same thread can lock multiple times
// - Internal counter tracks lock depth
// - Unlock counts must match lock counts
 
void recursive_example(void) {
    pthread_mutex_t mutex;
    pthread_mutexattr_t attr;
    
    pthread_mutexattr_init(&attr);
    pthread_mutexattr_settype(&attr, PTHREAD_MUTEX_RECURSIVE);
    pthread_mutex_init(&mutex, &attr);
    pthread_mutexattr_destroy(&attr);
    
    pthread_mutex_lock(&mutex);     // count = 1
    pthread_mutex_lock(&mutex);     // count = 2 (OK!)
    pthread_mutex_lock(&mutex);     // count = 3
    
    // Critical section
    
    pthread_mutex_unlock(&mutex);   // count = 2
    pthread_mutex_unlock(&mutex);   // count = 1
    pthread_mutex_unlock(&mutex);   // count = 0 (now truly unlocked)
    
    pthread_mutex_destroy(&mutex);
}

Choosing the Right Mutex Type

•Use NORMAL for production — When you're confident in correctness, NORMAL offers the best performance. Most production systems use this.
•Use ERRORCHECK for development — During development and testing, ERRORCHECK catches bugs that NORMAL would let through as undefined behavior.
•Use RECURSIVE when unavoidable — When the same thread must acquire a lock multiple times (e.g., recursive algorithms, callbacks into locked code).
•Avoid RECURSIVE if possible — Recursive mutexes often indicate design problems. Consider restructuring to separate locked and unlocked entry points.

The Recursive Mutex Trap

While recursive mutexes seem convenient, they often mask design problems. If you need recursive locking, it usually means your API boundaries are unclear. Consider refactoring: have public functions acquire the lock and call internal 'unlocked_' helper functions that assume the lock is held.

Core Operations: Lock, Unlock, Trylock

The pthread mutex API provides three primary operations for acquiring and releasing locks.

mutex_operations.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
#include <pthread.h>
#include <errno.h>
#include <time.h>
 
pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
 
// ═══════════════════════════════════════════════════════════
// pthread_mutex_lock - Blocking Acquire
// ═══════════════════════════════════════════════════════════
// Blocks until lock is acquired. Only returns when you own the lock.
// Returns: 0 on success, error code on failure
 
void blocking_acquire(void) {
    int result = pthread_mutex_lock(&lock);
    
    // In practice, pthread_mutex_lock almost never fails
    // Possible errors: EINVAL (not initialized), EDEADLK (errorcheck)
    if (result != 0) {
        // Handle error (rare for normal mutexes)
    }
    
    // CRITICAL SECTION: We own the lock
    do_protected_work();
    
    pthread_mutex_unlock(&lock);
}
 
// ═══════════════════════════════════════════════════════════
// pthread_mutex_trylock - Non-Blocking Attempt
// ═══════════════════════════════════════════════════════════
// Attempts to acquire lock. Returns immediately whether or not it got it.
// Returns: 0 if acquired, EBUSY if already held, other codes on error
 
void non_blocking_acquire(void) {
    int result = pthread_mutex_trylock(&lock);
    
    if (result == 0) {
        // Got the lock!
        do_protected_work();
        pthread_mutex_unlock(&lock);
    } else if (result == EBUSY) {
        // Lock is held by another thread
        // Do something else or try again later
        do_alternative_work();
    } else {
        // Other error (EINVAL, etc.)
        handle_error(result);
    }
}
 
// ═══════════════════════════════════════════════════════════
// pthread_mutex_timedlock - Bounded-Wait Acquire
// ═══════════════════════════════════════════════════════════
// Blocks until lock acquired OR timeout expires.
// The timeout is an ABSOLUTE time (not relative duration).
// Returns: 0 if acquired, ETIMEDOUT if timeout, other codes on error
 
void timed_acquire(void) {
    struct timespec timeout;
    
    // Get current time and add 2 seconds
    clock_gettime(CLOCK_REALTIME, &timeout);
    timeout.tv_sec += 2;  // Wait at most 2 seconds
    
    int result = pthread_mutex_timedlock(&lock, &timeout);
    
    if (result == 0) {
        // Got the lock within timeout
        do_protected_work();
        pthread_mutex_unlock(&lock);
    } else if (result == ETIMEDOUT) {
        // Timeout expired, lock not acquired
        printf("Timed out waiting for lock
");
    } else {
        // Other error
        handle_error(result);
    }
}
 
// ═══════════════════════════════════════════════════════════
// pthread_mutex_unlock - Release
// ═══════════════════════════════════════════════════════════
// Releases the lock. MUST be called by the owning thread.
// Returns: 0 on success, EPERM if not owner (for errorcheck/recursive)
 
void release_lock(void) {
    int result = pthread_mutex_unlock(&lock);
    
    // For NORMAL mutexes, unlocking from wrong thread is undefined!
    // For ERRORCHECK/RECURSIVE, returns EPERM
    if (result != 0) {
        // This is a serious bug in your program
        fprintf(stderr, "Failed to unlock: %d
", result);
    }
}

When to Use Each Operation

•pthread_mutex_lock — The default choice. Use when you must access the protected resource and can wait for it.
•pthread_mutex_trylock — Use when you can do something else if the lock is unavailable. Useful for lock-free algorithms, avoiding deadlock, or polling patterns.
•pthread_mutex_timedlock — Use when you need a bounded wait. Good for reactive systems where hanging indefinitely is unacceptable.

Absolute vs Relative Timeouts

pthread_mutex_timedlock uses an absolute timeout (CLOCK_REALTIME). If you want to wait for a relative duration (e.g., '2 seconds'), you must first get the current time and add your duration. Use clock_gettime(CLOCK_REALTIME, &ts) to get the current time.

Error Handling Best Practices

Pthread functions return error codes rather than setting errno (unlike most system calls). Proper error handling is essential for robust programs.

Common pthread_mutex Errors
Error	Meaning	When It Occurs
EINVAL	Invalid argument	Uninitialized mutex, invalid attributes
EBUSY	Resource busy	trylock: lock is held; destroy: lock is still held
EDEADLK	Deadlock detected	Errorcheck mutex: attempted relock by owner
EPERM	Permission denied	Unlock by non-owner (errorcheck/recursive)
ETIMEDOUT	Timeout expired	timedlock: time expired before acquiring
EOWNERDEAD	Owner died	Robust mutex: previous owner terminated

error_handling.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
 
// ─── HELPER: Describe pthread error ──────────────────────
// Note: strerror works for pthread error codes since they use errno values
 
void check_pthread_error(int result, const char *operation) {
    if (result != 0) {
        fprintf(stderr, "%s failed: %s (code %d)
", 
                operation, strerror(result), result);
        
        // Fatal errors should abort; recoverable errors can continue
        if (result == EINVAL || result == ENOMEM) {
            abort();  // Programming error or system failure
        }
    }
}
 
// ─── DEFENSIVE LOCKING ───────────────────────────────────
 
void defensive_lock_usage(pthread_mutex_t *mutex) {
    int result = pthread_mutex_lock(mutex);
    
    // For NORMAL mutexes, failure is extremely rare
    // But being defensive catches bugs during development
    check_pthread_error(result, "pthread_mutex_lock");
    
    // ... critical section ...
    
    result = pthread_mutex_unlock(mutex);
    check_pthread_error(result, "pthread_mutex_unlock");
}
 
// ─── GRACEFUL TRYLOCK HANDLING ───────────────────────────
 
int try_work_with_lock(pthread_mutex_t *mutex) {
    switch (pthread_mutex_trylock(mutex)) {
        case 0:
            // Success - do work and unlock
            do_work();
            pthread_mutex_unlock(mutex);
            return 1;  // Work completed
            
        case EBUSY:
            // Lock held - this is normal, not an error
            return 0;  // Work not done, try again later
            
        default:
            // Actual error - should not happen with properly initialized mutex
            fprintf(stderr, "Unexpected trylock error
");
            return -1;  // Error
    }
}
 
// ─── ROBUST MUTEX ERROR HANDLING ─────────────────────────
// Robust mutexes can detect when the owner died while holding the lock
 
void robust_mutex_handler(pthread_mutex_t *mutex) {
    int result = pthread_mutex_lock(mutex);
    
    if (result == EOWNERDEAD) {
        // Previous owner terminated while holding lock!
        // Protected data may be in inconsistent state
        
        printf("Previous owner died. Trying to recover...
");
        
        // Option 1: Repair state and mark mutex consistent
        if (can_repair_state()) {
            repair_protected_data();
            pthread_mutex_consistent(mutex);
            // Now use the lock normally
            pthread_mutex_unlock(mutex);
        } else {
            // Option 2: Cannot repair, leave mutex unusable
            // Other threads will also get ENOTRECOVERABLE
            pthread_mutex_unlock(mutex);
        }
    } else if (result == ENOTRECOVERABLE) {
        // Mutex is permanently unusable (not made consistent after EOWNERDEAD)
        fprintf(stderr, "Mutex is not recoverable
");
        abort();
    }
}

Error Checking Philosophy

In debug builds: check every return value and abort on errors. In release builds with NORMAL mutexes: checking is optional since errors are undefined behavior anyway. The real defense is correct code, not error checking. That said, checking lock/unlock in both builds is cheap insurance against subtle bugs.

Initialization and Destruction

Proper lifecycle management of mutexes is critical for avoiding resource leaks and undefined behavior.

mutex_lifecycle.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
#include <pthread.h>
#include <stdlib.h>
 
// ═══════════════════════════════════════════════════════════
// STATIC MUTEX LIFECYCLE
// ═══════════════════════════════════════════════════════════
// Static/global mutexes exist for program lifetime
 
static pthread_mutex_t global_data_lock = PTHREAD_MUTEX_INITIALIZER;
// No explicit init needed
// Destruction is optional at program termination
// (OS reclaims resources anyway)
 
// ═══════════════════════════════════════════════════════════
// DYNAMIC MUTEX LIFECYCLE
// ═══════════════════════════════════════════════════════════
typedef struct {
    pthread_mutex_t lock;
    int *data;
    size_t size;
} protected_buffer_t;
 
protected_buffer_t* buffer_create(size_t size) {
    protected_buffer_t *buf = malloc(sizeof(*buf));
    if (!buf) return NULL;
    
    // Initialize mutex BEFORE first use
    int result = pthread_mutex_init(&buf->lock, NULL);
    if (result != 0) {
        free(buf);
        return NULL;
    }
    
    buf->data = malloc(size * sizeof(int));
    if (!buf->data) {
        pthread_mutex_destroy(&buf->lock);
        free(buf);
        return NULL;
    }
    
    buf->size = size;
    return buf;
}
 
void buffer_destroy(protected_buffer_t *buf) {
    if (!buf) return;
    
    // IMPORTANT: Ensure no thread is using the mutex!
    // Destroying a locked mutex is undefined behavior.
    
    // Option 1: Just destroy (caller guarantees no users)
    int result = pthread_mutex_destroy(&buf->lock);
    if (result == EBUSY) {
        // Mutex is still locked! This is a bug in caller code.
        fprintf(stderr, "Cannot destroy locked mutex!
");
        abort();
    }
    
    free(buf->data);
    free(buf);
}
 
// ═══════════════════════════════════════════════════════════
// EMBEDDED MUTEX LIFECYCLE
// ═══════════════════════════════════════════════════════════
// When mutex is embedded in another struct (not a pointer)
 
typedef struct node {
    pthread_mutex_t lock;
    int value;
    struct node *next;
} node_t;
 
node_t* node_create(int value) {
    node_t *node = malloc(sizeof(*node));
    if (!node) return NULL;
    
    if (pthread_mutex_init(&node->lock, NULL) != 0) {
        free(node);
        return NULL;
    }
    
    node->value = value;
    node->next = NULL;
    return node;
}
 
void node_destroy(node_t *node) {
    // Destroy mutex before freeing memory
    pthread_mutex_destroy(&node->lock);
    free(node);
    // Note: accessing node->lock after free is undefined behavior!
}

Critical Lifecycle Rules

•Never destroy a locked mutex — Undefined behavior. Ensure all users have released it.
•Never use an uninitialized mutex — Undefined behavior. Always initialize before first lock.
•Never use a destroyed mutex — Once destroyed, reinitialize before use or leave it alone.
•Never copy mutexes — Copying pthread_mutex_t is undefined. Each mutex must be individually initialized.
•Destroy before freeing memory — If mutex is in heap-allocated struct, destroy the mutex before freeing the struct.

Static Initialization Caveat

PTHREAD_MUTEX_INITIALIZER works for static storage duration objects. For automatic (stack) variables, it's technically allowed but risky—the variable may contain garbage if the initializer is not applied correctly. Use pthread_mutex_init for stack-allocated mutexes to be safe.

Process-Shared Mutexes

By default, pthread mutexes are process-private—they can only synchronize threads within a single process. However, mutexes can be configured to work across process boundaries when placed in shared memory.

process_shared_mutex.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
#include <pthread.h>
#include <sys/mman.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdio.h>
#include <sys/wait.h>
 
// Shared memory layout
typedef struct {
    pthread_mutex_t mutex;
    int counter;
} shared_data_t;
 
int main() {
    // ─── 1. Create shared memory ────────────────────────
    shared_data_t *shared = mmap(
        NULL, sizeof(shared_data_t),
        PROT_READ | PROT_WRITE,
        MAP_SHARED | MAP_ANONYMOUS,  // Shared between parent/child
        -1, 0
    );
    
    // ─── 2. Initialize process-shared mutex ─────────────
    pthread_mutexattr_t attr;
    pthread_mutexattr_init(&attr);
    pthread_mutexattr_setpshared(&attr, PTHREAD_PROCESS_SHARED);
    
    // RECOMMENDED: Also make it robust
    // If one process dies holding the lock, others can recover
    pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
    
    pthread_mutex_init(&shared->mutex, &attr);
    pthread_mutexattr_destroy(&attr);
    
    shared->counter = 0;
    
    // ─── 3. Fork child process ──────────────────────────
    pid_t pid = fork();
    
    if (pid == 0) {
        // CHILD PROCESS
        for (int i = 0; i < 100000; i++) {
            pthread_mutex_lock(&shared->mutex);
            shared->counter++;
            pthread_mutex_unlock(&shared->mutex);
        }
        _exit(0);
    } else {
        // PARENT PROCESS
        for (int i = 0; i < 100000; i++) {
            pthread_mutex_lock(&shared->mutex);
            shared->counter++;
            pthread_mutex_unlock(&shared->mutex);
        }
        
        waitpid(pid, NULL, 0);
        
        // Counter should be exactly 200000 (no races!)
        printf("Counter: %d (expected 200000)
", shared->counter);
    }
    
    pthread_mutex_destroy(&shared->mutex);
    munmap(shared, sizeof(shared_data_t));
    
    return 0;
}

Process-Shared Mutex Requirements

•Must be in shared memory — The mutex must be allocated in memory accessible by all participating processes (mmap, shm_open, etc.).
•PTHREAD_PROCESS_SHARED attribute — Set with pthread_mutexattr_setpshared before initialization.
•Consider robust mutexes — If one process dies holding the lock, robust mutexes allow recovery.
•Initialize once — Only one process should initialize the mutex. Others map the existing shared memory.
•Portable considerations — Not all systems fully support process-shared mutexes. Check implementation documentation.

When to Use Process-Shared Mutexes

Process-shared mutexes are useful for: database shared buffer pools, IPC through shared memory, multi-process server architectures, and cache synchronization between worker processes. They're more efficient than file locking or other IPC mechanisms for protecting shared memory.

Operating SystemsMutex Locks

Mutex Locks: Mutual Exclusion Primitives

LevelIntermediate

Duration60 mins

TopicMutex Locks

4 / 5

Pthread Mutex: The POSIX Standard API

The Industry Standard

Having understood mutex concepts and implementation, we now turn to the practical API that millions of developers use daily: POSIX threads (pthreads) . The pthread mutex API is the standard interface for mutex synchronization on Linux, macOS, BSD, and virtually every Unix-like operating system. Mastering pthread mutexes is essential for any systems programmer. Whether you're building servers, databases, operating systems, or high-performance applications, you will encounter pthreads. Understanding not just what the API does, but why it's designed this way, will make you a more effective engineer.

What You Will Learn

By the end of this page, you will master the pthread_mutex API: initialization options, attribute configuration, type selection, operation semantics, error handling, and production best practices. You will understand the tradeoffs between different mutex types and know how to avoid common pitfalls.

The pthread_mutex_t Type

The core of the pthread mutex API is the pthread_mutex_t type—an opaque data structure representing a mutex. Key Characteristics: Opaque structure: You cannot access or manipulate its internal fields directly. It must be used only through pthread_mutex_* functions. Fixed size: The size is ABI-defined and constant on a given platform (though it varies between OSes). Not copyable: You cannot simply copy a mutex with = . Two mutexes must be separately initialized. Initialization required: A mutex must be initialized before use, either statically or dynamically.

pthread_mutex_basics.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
#include <pthread.h>
#include <stdio.h>
 
// ─── METHOD 1: STATIC INITIALIZATION ──────────────────────
// Use when mutex is a global or static variable
// No cleanup needed (but pthread_mutex_destroy is still safe to call)
 
static pthread_mutex_t global_lock = PTHREAD_MUTEX_INITIALIZER;
 
// ─── METHOD 2: DYNAMIC INITIALIZATION ─────────────────────
// Use when mutex is allocated dynamically or needs custom attributes
// Must call pthread_mutex_destroy when done
 
void dynamic_example(void) {
    pthread_mutex_t* dynamic_lock = malloc(sizeof(pthread_mutex_t));
    
    // Initialize with default attributes (NULL)
    int result = pthread_mutex_init(dynamic_lock, NULL);
    if (result != 0) {
        fprintf(stderr, "Mutex init failed: %d
", result);
        exit(1);
    }
    
    // ... use the mutex ...
    
    // Clean up when done
    pthread_mutex_destroy(dynamic_lock);
    free(dynamic_lock);
}
 
// ─── CRITICAL POINTS ──────────────────────────────────────
// 
// 1. PTHREAD_MUTEX_INITIALIZER is a MACRO that expands to a
//    brace-enclosed initializer. It can ONLY be used at declaration.
//
// 2. You cannot use PTHREAD_MUTEX_INITIALIZER for assignment:
//    pthread_mutex_t m;
//    m = PTHREAD_MUTEX_INITIALIZER;  // WRONG! Compile error.
//
// 3. For non-default attributes, you MUST use pthread_mutex_init.
//
// 4. pthread_mutex_destroy releases any resources. After destroy,
//    the mutex is in an undefined state until reinitialized.

When to Use Static vs Dynamic Initialization

Static: Use PTHREAD_MUTEX_INITIALIZER for global/static mutexes with default attributes. It's simpler and slightly faster (no function call). Dynamic: Use pthread_mutex_init when you need custom attributes (error-checking, recursive), when the mutex is heap-allocated, or when initializing an array of mutexes.

Mutex Attributes (pthread_mutexattr_t)

Mutex behavior can be customized through attributes . The pthread_mutexattr_t type holds configuration options that are passed to pthread_mutex_init . Available Attributes:

Pthread Mutex Attributes
Attribute	Function	Purpose
Type	`pthread_mutexattr_settype()`	Normal, error-checking, recursive, or default behavior
Protocol	`pthread_mutexattr_setprotocol()`	Priority inheritance, priority ceiling, or none
Priority Ceiling	`pthread_mutexattr_setprioceiling()`	Maximum priority when using ceiling protocol
Process-Shared	`pthread_mutexattr_setpshared()`	Can mutex be shared between processes?
Robust	`pthread_mutexattr_setrobust()`	Behavior when owner terminates holding lock

mutex_attributes.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
#include <pthread.h>
 
// Creating a mutex with custom attributes
 
int create_recursive_mutex(pthread_mutex_t* mutex) {
    pthread_mutexattr_t attr;
    int result;
    
    // Step 1: Initialize the attribute object
    result = pthread_mutexattr_init(&attr);
    if (result != 0) return result;
    
    // Step 2: Configure desired attributes
    result = pthread_mutexattr_settype(&attr, PTHREAD_MUTEX_RECURSIVE);
    if (result != 0) {
        pthread_mutexattr_destroy(&attr);
        return result;
    }
    
    // Step 3: Create the mutex with these attributes
    result = pthread_mutex_init(mutex, &attr);
    
    // Step 4: Clean up the attribute object (mutex keeps its settings)
    pthread_mutexattr_destroy(&attr);
    
    return result;
}
 
// Creating an error-checking mutex
int create_errorcheck_mutex(pthread_mutex_t* mutex) {
    pthread_mutexattr_t attr;
    pthread_mutexattr_init(&attr);
    pthread_mutexattr_settype(&attr, PTHREAD_MUTEX_ERRORCHECK);
    int result = pthread_mutex_init(mutex, &attr);
    pthread_mutexattr_destroy(&attr);
    return result;
}
 
// Creating a process-shared mutex (for shared memory between processes)
int create_shared_mutex(pthread_mutex_t* mutex) {
    pthread_mutexattr_t attr;
    pthread_mutexattr_init(&attr);
    pthread_mutexattr_setpshared(&attr, PTHREAD_PROCESS_SHARED);
    int result = pthread_mutex_init(mutex, &attr);
    pthread_mutexattr_destroy(&attr);
    return result;
}

Attribute Object Lifecycle

The pthread_mutexattr_t object is only used during pthread_mutex_init. After initialization, the mutex has its own copy of the settings. You can destroy the attribute object immediately after init, or reuse it to create multiple mutexes with the same settings.

Mutex Types: Behavior Variants

POSIX defines four mutex types, each with different behavior for edge cases like relocking by the same thread or unlocking by a different thread.

POSIX Mutex Types Comparison
Type	Relock by Owner	Unlock by Non-Owner	Unlock when Unlocked	Use Case
PTHREAD_MUTEX_NORMAL	Deadlock	Undefined	Undefined	Performance-critical, trusted code
PTHREAD_MUTEX_ERRORCHECK	Returns EDEADLK	Returns EPERM	Returns EPERM	Development, debugging
PTHREAD_MUTEX_RECURSIVE	Succeeds (count++)	Returns EPERM	Returns EPERM	Reentrant code, callbacks
PTHREAD_MUTEX_DEFAULT	Undefined	Undefined	Undefined	Implementation-defined (often = NORMAL)

mutex_types_examples.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
#include <pthread.h>
#include <stdio.h>
#include <errno.h>
 
// ═══════════════════════════════════════════════════════════
// NORMAL MUTEX
// ═══════════════════════════════════════════════════════════
// - Fastest (minimal checking)
// - Undefined behavior on misuse (deadlock, corruption, etc.)
// - Use when you are 100% confident in correct usage
 
pthread_mutex_t normal_mutex = PTHREAD_MUTEX_INITIALIZER;
 
void normal_example(void) {
    pthread_mutex_lock(&normal_mutex);
    
    // BUG: Attempting to lock again causes DEADLOCK
    // pthread_mutex_lock(&normal_mutex);  // Hangs forever!
    
    pthread_mutex_unlock(&normal_mutex);
}
 
// ═══════════════════════════════════════════════════════════
// ERROR-CHECKING MUTEX  
// ═══════════════════════════════════════════════════════════
// - Detects common errors (double lock, wrong unlock)
// - Returns error codes instead of undefined behavior
// - Slight overhead from additional checks
 
void errorcheck_example(void) {
    pthread_mutex_t mutex;
    pthread_mutexattr_t attr;
    
    pthread_mutexattr_init(&attr);
    pthread_mutexattr_settype(&attr, PTHREAD_MUTEX_ERRORCHECK);
    pthread_mutex_init(&mutex, &attr);
    pthread_mutexattr_destroy(&attr);
    
    pthread_mutex_lock(&mutex);
    
    // Attempt to lock again - returns EDEADLK instead of deadlocking
    int result = pthread_mutex_lock(&mutex);
    if (result == EDEADLK) {
        printf("Error: Detected attempt to relock owned mutex!
");
    }
    
    pthread_mutex_unlock(&mutex);
    
    // Attempt to unlock when not locked - returns EPERM
    result = pthread_mutex_unlock(&mutex);
    if (result == EPERM) {
        printf("Error: Detected attempt to unlock non-owned mutex!
");
    }
    
    pthread_mutex_destroy(&mutex);
}
 
// ═══════════════════════════════════════════════════════════
// RECURSIVE MUTEX
// ═══════════════════════════════════════════════════════════
// - Same thread can lock multiple times
// - Internal counter tracks lock depth
// - Unlock counts must match lock counts
 
void recursive_example(void) {
    pthread_mutex_t mutex;
    pthread_mutexattr_t attr;
    
    pthread_mutexattr_init(&attr);
    pthread_mutexattr_settype(&attr, PTHREAD_MUTEX_RECURSIVE);
    pthread_mutex_init(&mutex, &attr);
    pthread_mutexattr_destroy(&attr);
    
    pthread_mutex_lock(&mutex);     // count = 1
    pthread_mutex_lock(&mutex);     // count = 2 (OK!)
    pthread_mutex_lock(&mutex);     // count = 3
    
    // Critical section
    
    pthread_mutex_unlock(&mutex);   // count = 2
    pthread_mutex_unlock(&mutex);   // count = 1
    pthread_mutex_unlock(&mutex);   // count = 0 (now truly unlocked)
    
    pthread_mutex_destroy(&mutex);
}

Choosing the Right Mutex Type

•Use NORMAL for production — When you're confident in correctness, NORMAL offers the best performance. Most production systems use this.
•Use ERRORCHECK for development — During development and testing, ERRORCHECK catches bugs that NORMAL would let through as undefined behavior.
•Use RECURSIVE when unavoidable — When the same thread must acquire a lock multiple times (e.g., recursive algorithms, callbacks into locked code).
•Avoid RECURSIVE if possible — Recursive mutexes often indicate design problems. Consider restructuring to separate locked and unlocked entry points.

The Recursive Mutex Trap

While recursive mutexes seem convenient, they often mask design problems. If you need recursive locking, it usually means your API boundaries are unclear. Consider refactoring: have public functions acquire the lock and call internal 'unlocked_' helper functions that assume the lock is held.

Core Operations: Lock, Unlock, Trylock

The pthread mutex API provides three primary operations for acquiring and releasing locks.

mutex_operations.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
#include <pthread.h>
#include <errno.h>
#include <time.h>
 
pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;
 
// ═══════════════════════════════════════════════════════════
// pthread_mutex_lock - Blocking Acquire
// ═══════════════════════════════════════════════════════════
// Blocks until lock is acquired. Only returns when you own the lock.
// Returns: 0 on success, error code on failure
 
void blocking_acquire(void) {
    int result = pthread_mutex_lock(&lock);
    
    // In practice, pthread_mutex_lock almost never fails
    // Possible errors: EINVAL (not initialized), EDEADLK (errorcheck)
    if (result != 0) {
        // Handle error (rare for normal mutexes)
    }
    
    // CRITICAL SECTION: We own the lock
    do_protected_work();
    
    pthread_mutex_unlock(&lock);
}
 
// ═══════════════════════════════════════════════════════════
// pthread_mutex_trylock - Non-Blocking Attempt
// ═══════════════════════════════════════════════════════════
// Attempts to acquire lock. Returns immediately whether or not it got it.
// Returns: 0 if acquired, EBUSY if already held, other codes on error
 
void non_blocking_acquire(void) {
    int result = pthread_mutex_trylock(&lock);
    
    if (result == 0) {
        // Got the lock!
        do_protected_work();
        pthread_mutex_unlock(&lock);
    } else if (result == EBUSY) {
        // Lock is held by another thread
        // Do something else or try again later
        do_alternative_work();
    } else {
        // Other error (EINVAL, etc.)
        handle_error(result);
    }
}
 
// ═══════════════════════════════════════════════════════════
// pthread_mutex_timedlock - Bounded-Wait Acquire
// ═══════════════════════════════════════════════════════════
// Blocks until lock acquired OR timeout expires.
// The timeout is an ABSOLUTE time (not relative duration).
// Returns: 0 if acquired, ETIMEDOUT if timeout, other codes on error
 
void timed_acquire(void) {
    struct timespec timeout;
    
    // Get current time and add 2 seconds
    clock_gettime(CLOCK_REALTIME, &timeout);
    timeout.tv_sec += 2;  // Wait at most 2 seconds
    
    int result = pthread_mutex_timedlock(&lock, &timeout);
    
    if (result == 0) {
        // Got the lock within timeout
        do_protected_work();
        pthread_mutex_unlock(&lock);
    } else if (result == ETIMEDOUT) {
        // Timeout expired, lock not acquired
        printf("Timed out waiting for lock
");
    } else {
        // Other error
        handle_error(result);
    }
}
 
// ═══════════════════════════════════════════════════════════
// pthread_mutex_unlock - Release
// ═══════════════════════════════════════════════════════════
// Releases the lock. MUST be called by the owning thread.
// Returns: 0 on success, EPERM if not owner (for errorcheck/recursive)
 
void release_lock(void) {
    int result = pthread_mutex_unlock(&lock);
    
    // For NORMAL mutexes, unlocking from wrong thread is undefined!
    // For ERRORCHECK/RECURSIVE, returns EPERM
    if (result != 0) {
        // This is a serious bug in your program
        fprintf(stderr, "Failed to unlock: %d
", result);
    }
}

When to Use Each Operation

•pthread_mutex_lock — The default choice. Use when you must access the protected resource and can wait for it.
•pthread_mutex_trylock — Use when you can do something else if the lock is unavailable. Useful for lock-free algorithms, avoiding deadlock, or polling patterns.
•pthread_mutex_timedlock — Use when you need a bounded wait. Good for reactive systems where hanging indefinitely is unacceptable.

Absolute vs Relative Timeouts

pthread_mutex_timedlock uses an absolute timeout (CLOCK_REALTIME). If you want to wait for a relative duration (e.g., '2 seconds'), you must first get the current time and add your duration. Use clock_gettime(CLOCK_REALTIME, &ts) to get the current time.

Error Handling Best Practices

Pthread functions return error codes rather than setting errno (unlike most system calls). Proper error handling is essential for robust programs.

Common pthread_mutex Errors
Error	Meaning	When It Occurs
EINVAL	Invalid argument	Uninitialized mutex, invalid attributes
EBUSY	Resource busy	trylock: lock is held; destroy: lock is still held
EDEADLK	Deadlock detected	Errorcheck mutex: attempted relock by owner
EPERM	Permission denied	Unlock by non-owner (errorcheck/recursive)
ETIMEDOUT	Timeout expired	timedlock: time expired before acquiring
EOWNERDEAD	Owner died	Robust mutex: previous owner terminated

error_handling.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
 
// ─── HELPER: Describe pthread error ──────────────────────
// Note: strerror works for pthread error codes since they use errno values
 
void check_pthread_error(int result, const char *operation) {
    if (result != 0) {
        fprintf(stderr, "%s failed: %s (code %d)
", 
                operation, strerror(result), result);
        
        // Fatal errors should abort; recoverable errors can continue
        if (result == EINVAL || result == ENOMEM) {
            abort();  // Programming error or system failure
        }
    }
}
 
// ─── DEFENSIVE LOCKING ───────────────────────────────────
 
void defensive_lock_usage(pthread_mutex_t *mutex) {
    int result = pthread_mutex_lock(mutex);
    
    // For NORMAL mutexes, failure is extremely rare
    // But being defensive catches bugs during development
    check_pthread_error(result, "pthread_mutex_lock");
    
    // ... critical section ...
    
    result = pthread_mutex_unlock(mutex);
    check_pthread_error(result, "pthread_mutex_unlock");
}
 
// ─── GRACEFUL TRYLOCK HANDLING ───────────────────────────
 
int try_work_with_lock(pthread_mutex_t *mutex) {
    switch (pthread_mutex_trylock(mutex)) {
        case 0:
            // Success - do work and unlock
            do_work();
            pthread_mutex_unlock(mutex);
            return 1;  // Work completed
            
        case EBUSY:
            // Lock held - this is normal, not an error
            return 0;  // Work not done, try again later
            
        default:
            // Actual error - should not happen with properly initialized mutex
            fprintf(stderr, "Unexpected trylock error
");
            return -1;  // Error
    }
}
 
// ─── ROBUST MUTEX ERROR HANDLING ─────────────────────────
// Robust mutexes can detect when the owner died while holding the lock
 
void robust_mutex_handler(pthread_mutex_t *mutex) {
    int result = pthread_mutex_lock(mutex);
    
    if (result == EOWNERDEAD) {
        // Previous owner terminated while holding lock!
        // Protected data may be in inconsistent state
        
        printf("Previous owner died. Trying to recover...
");
        
        // Option 1: Repair state and mark mutex consistent
        if (can_repair_state()) {
            repair_protected_data();
            pthread_mutex_consistent(mutex);
            // Now use the lock normally
            pthread_mutex_unlock(mutex);
        } else {
            // Option 2: Cannot repair, leave mutex unusable
            // Other threads will also get ENOTRECOVERABLE
            pthread_mutex_unlock(mutex);
        }
    } else if (result == ENOTRECOVERABLE) {
        // Mutex is permanently unusable (not made consistent after EOWNERDEAD)
        fprintf(stderr, "Mutex is not recoverable
");
        abort();
    }
}

Error Checking Philosophy

In debug builds: check every return value and abort on errors. In release builds with NORMAL mutexes: checking is optional since errors are undefined behavior anyway. The real defense is correct code, not error checking. That said, checking lock/unlock in both builds is cheap insurance against subtle bugs.

Initialization and Destruction

Proper lifecycle management of mutexes is critical for avoiding resource leaks and undefined behavior.

mutex_lifecycle.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
#include <pthread.h>
#include <stdlib.h>
 
// ═══════════════════════════════════════════════════════════
// STATIC MUTEX LIFECYCLE
// ═══════════════════════════════════════════════════════════
// Static/global mutexes exist for program lifetime
 
static pthread_mutex_t global_data_lock = PTHREAD_MUTEX_INITIALIZER;
// No explicit init needed
// Destruction is optional at program termination
// (OS reclaims resources anyway)
 
// ═══════════════════════════════════════════════════════════
// DYNAMIC MUTEX LIFECYCLE
// ═══════════════════════════════════════════════════════════
typedef struct {
    pthread_mutex_t lock;
    int *data;
    size_t size;
} protected_buffer_t;
 
protected_buffer_t* buffer_create(size_t size) {
    protected_buffer_t *buf = malloc(sizeof(*buf));
    if (!buf) return NULL;
    
    // Initialize mutex BEFORE first use
    int result = pthread_mutex_init(&buf->lock, NULL);
    if (result != 0) {
        free(buf);
        return NULL;
    }
    
    buf->data = malloc(size * sizeof(int));
    if (!buf->data) {
        pthread_mutex_destroy(&buf->lock);
        free(buf);
        return NULL;
    }
    
    buf->size = size;
    return buf;
}
 
void buffer_destroy(protected_buffer_t *buf) {
    if (!buf) return;
    
    // IMPORTANT: Ensure no thread is using the mutex!
    // Destroying a locked mutex is undefined behavior.
    
    // Option 1: Just destroy (caller guarantees no users)
    int result = pthread_mutex_destroy(&buf->lock);
    if (result == EBUSY) {
        // Mutex is still locked! This is a bug in caller code.
        fprintf(stderr, "Cannot destroy locked mutex!
");
        abort();
    }
    
    free(buf->data);
    free(buf);
}
 
// ═══════════════════════════════════════════════════════════
// EMBEDDED MUTEX LIFECYCLE
// ═══════════════════════════════════════════════════════════
// When mutex is embedded in another struct (not a pointer)
 
typedef struct node {
    pthread_mutex_t lock;
    int value;
    struct node *next;
} node_t;
 
node_t* node_create(int value) {
    node_t *node = malloc(sizeof(*node));
    if (!node) return NULL;
    
    if (pthread_mutex_init(&node->lock, NULL) != 0) {
        free(node);
        return NULL;
    }
    
    node->value = value;
    node->next = NULL;
    return node;
}
 
void node_destroy(node_t *node) {
    // Destroy mutex before freeing memory
    pthread_mutex_destroy(&node->lock);
    free(node);
    // Note: accessing node->lock after free is undefined behavior!
}

Critical Lifecycle Rules

•Never destroy a locked mutex — Undefined behavior. Ensure all users have released it.
•Never use an uninitialized mutex — Undefined behavior. Always initialize before first lock.
•Never use a destroyed mutex — Once destroyed, reinitialize before use or leave it alone.
•Never copy mutexes — Copying pthread_mutex_t is undefined. Each mutex must be individually initialized.
•Destroy before freeing memory — If mutex is in heap-allocated struct, destroy the mutex before freeing the struct.

Static Initialization Caveat

PTHREAD_MUTEX_INITIALIZER works for static storage duration objects. For automatic (stack) variables, it's technically allowed but risky—the variable may contain garbage if the initializer is not applied correctly. Use pthread_mutex_init for stack-allocated mutexes to be safe.

Process-Shared Mutexes

By default, pthread mutexes are process-private—they can only synchronize threads within a single process. However, mutexes can be configured to work across process boundaries when placed in shared memory.

process_shared_mutex.c
C
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
#include <pthread.h>
#include <sys/mman.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdio.h>
#include <sys/wait.h>
 
// Shared memory layout
typedef struct {
    pthread_mutex_t mutex;
    int counter;
} shared_data_t;
 
int main() {
    // ─── 1. Create shared memory ────────────────────────
    shared_data_t *shared = mmap(
        NULL, sizeof(shared_data_t),
        PROT_READ | PROT_WRITE,
        MAP_SHARED | MAP_ANONYMOUS,  // Shared between parent/child
        -1, 0
    );
    
    // ─── 2. Initialize process-shared mutex ─────────────
    pthread_mutexattr_t attr;
    pthread_mutexattr_init(&attr);
    pthread_mutexattr_setpshared(&attr, PTHREAD_PROCESS_SHARED);
    
    // RECOMMENDED: Also make it robust
    // If one process dies holding the lock, others can recover
    pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST);
    
    pthread_mutex_init(&shared->mutex, &attr);
    pthread_mutexattr_destroy(&attr);
    
    shared->counter = 0;
    
    // ─── 3. Fork child process ──────────────────────────
    pid_t pid = fork();
    
    if (pid == 0) {
        // CHILD PROCESS
        for (int i = 0; i < 100000; i++) {
            pthread_mutex_lock(&shared->mutex);
            shared->counter++;
            pthread_mutex_unlock(&shared->mutex);
        }
        _exit(0);
    } else {
        // PARENT PROCESS
        for (int i = 0; i < 100000; i++) {
            pthread_mutex_lock(&shared->mutex);
            shared->counter++;
            pthread_mutex_unlock(&shared->mutex);
        }
        
        waitpid(pid, NULL, 0);
        
        // Counter should be exactly 200000 (no races!)
        printf("Counter: %d (expected 200000)
", shared->counter);
    }
    
    pthread_mutex_destroy(&shared->mutex);
    munmap(shared, sizeof(shared_data_t));
    
    return 0;
}

Process-Shared Mutex Requirements

•Must be in shared memory — The mutex must be allocated in memory accessible by all participating processes (mmap, shm_open, etc.).
•PTHREAD_PROCESS_SHARED attribute — Set with pthread_mutexattr_setpshared before initialization.
•Consider robust mutexes — If one process dies holding the lock, robust mutexes allow recovery.
•Initialize once — Only one process should initialize the mutex. Others map the existing shared memory.
•Portable considerations — Not all systems fully support process-shared mutexes. Check implementation documentation.

When to Use Process-Shared Mutexes

Process-shared mutexes are useful for: database shared buffer pools, IPC through shared memory, multi-process server architectures, and cache synchronization between worker processes. They're more efficient than file locking or other IPC mechanisms for protecting shared memory.

Pthread Mutex: The POSIX Standard API

The Industry Standard

The pthread_mutex_t Type

Mutex Attributes (pthread_mutexattr_t)

Mutex Types: Behavior Variants

Core Operations: Lock, Unlock, Trylock

Error Handling Best Practices

Initialization and Destruction

Process-Shared Mutexes

There’s more to understand.

Pthread Mutex: The POSIX Standard API

The Industry Standard

The pthread_mutex_t Type

Mutex Attributes (pthread_mutexattr_t)

Mutex Types: Behavior Variants

Core Operations: Lock, Unlock, Trylock

Error Handling Best Practices

Initialization and Destruction

Process-Shared Mutexes

There’s more to understand.