pthread_mutex: move in from cpp-cheat

README.adoc

@@ -13674,6 +13674,11 @@ time ./std_atomic.out 4 100000000
 time ./mutex.out 4 100000000
 ....
 
+Related examples:
+
+* POSIX <<pthread-mutex>>
+* C11 link:userland/c/atomic.c[] documented at <<c-multithreading>>
+
 Bibliography:
 
 * https://stackoverflow.com/questions/31978324/what-exactly-is-stdatomic/58904448#58904448 "What exactly is std::atomic?"
@@ -13754,6 +13759,23 @@ This was for a looong time the only "portable" multithreading alternative, until
 * link:userland/posix/pthread_deadlock.c[]
 * link:userland/posix/pthread_self.c[]
 
+[[pthread-mutex]]
+===== pthread_mutex
+
+link:userland/posix/pthread_count.c[] exemplifies the functions:
+
+* `pthread_mutex_lock`
+* pthread_mutex_unlock
+
+That example that the same interface as: <<atomic-cpp>>.
+There are no non-locking atomic types or atomic primitives in POSIX: http://stackoverflow.com/questions/1130018/unix-portable-atomic-operations
+
+`pthread_mutex_lock` and `pthread_mutex_unlock` and many other pthread functions already enforce cross thread memory synchronization:
+
+* https://stackoverflow.com/questions/78172/using-c-pthreads-do-shared-variables-need-to-be-volatile/58935671#58935671
+* https://stackoverflow.com/questions/3208060/does-guarding-a-variable-with-a-pthread-mutex-guarantee-its-also-not-cached
+* https://stackoverflow.com/questions/24137964/does-pthread-mutex-lock-contains-memory-fence-instruction
+
 ==== sysconf
 
 https://pubs.opengroup.org/onlinepubs/9699919799/functions/sysconf.html
@@ -13937,7 +13959,7 @@ It is also possible to the algorithm tests normally from emulators in <<user-mod
 
 Sources:
 
-* link:userland/algorithm/set/generate_input[]
+* link:userland/algorithm/set/generate_io[]
 * link:userland/algorithm/set/main.hpp[]
 * link:userland/algorithm/set/parse_output[]
 * link:userland/algorithm/set/std_set.cpp[]

path_properties.py

@@ -696,6 +696,9 @@ path_properties_tuples = (
                             'more_than_1s': True,
                             'test_run_args': {'cpus': 2},
                         },
+                        'pthread_mutex.c': {
+                            'test_run_args': {'cpus': 3},
+                        },
                         'pthread_self.c': {
                             'test_run_args': {'cpus': 2},
                         },

userland/posix/pthread_mutex.c

@@ -0,0 +1,52 @@
+/* https://cirosantilli.com/linux-kernel-module-cheat#pthread-mutex */
+
+#define _XOPEN_SOURCE 700
+#include <assert.h>
+#include <pthread.h>
+#include <stdlib.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+unsigned long long niters;
+unsigned long long global = 0;
+pthread_mutex_t main_thread_mutex = PTHREAD_MUTEX_INITIALIZER;
+
+void* main_thread(void *arg) {
+    (void)arg;
+    unsigned long long i;
+    for (i = 0; i < niters; ++i) {
+        pthread_mutex_lock(&main_thread_mutex);
+        global++;
+        pthread_mutex_unlock(&main_thread_mutex);
+    }
+    return NULL;
+}
+
+int main(int argc, char **argv) {
+    pthread_t *threads;
+    unsigned long long i, nthreads;
+
+    /* CLI arguments. */
+    if (argc > 1) {
+        nthreads = strtoull(argv[1], NULL, 0);
+    } else {
+        nthreads = 2;
+    }
+    if (argc > 2) {
+        niters = strtoull(argv[2], NULL, 0);
+    } else {
+        niters = 10;
+    }
+    threads = malloc(sizeof(pthread_t) * nthreads);
+
+    /* Action */
+    for (i = 0; i < nthreads; ++i)
+        pthread_create(&threads[i], NULL, main_thread, NULL);
+    for (i = 0; i < nthreads; ++i)
+        pthread_join(threads[i], NULL);
+    assert(global == nthreads * niters);
+
+    /* Cleanup. */
+    free(threads);
+    return EXIT_SUCCESS;
+}