Re: notation for documenting multithread-safety

[Bruno Haible]

Here's the proposed macro.

The file glibc/manual/macros.texi contains documentation annotations for
MT-safety, along similar lines. I didn't use this nomenclature because it
is based on what the functions internally do; I prefer a nomenclature which
is about what the caller of the function can expect or must guarantee.


2019-12-01  Bruno Haible  <address@hidden>

        Add infrastructure for documenting multi-thread safety.
        * m4/gnulib-common.m4 (gl_COMMON_BODY): Declare C macros _GL_MT_SAFE,
        _GL_NOT_MT_SAFE.

diff --git a/m4/gnulib-common.m4 b/m4/gnulib-common.m4
index 479c9de..ca0d400 100644
--- a/m4/gnulib-common.m4
+++ b/m4/gnulib-common.m4
@@ -1,4 +1,4 @@
-# gnulib-common.m4 serial 45
+# gnulib-common.m4 serial 46
 dnl Copyright (C) 2007-2019 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
@@ -115,6 +115,48 @@ AC_DEFUN([gl_COMMON_BODY], [
        errno.  */
 #define _GL_ASYNC_SAFE
 ])
+  AH_VERBATIM([multithread_safe],
+[/* A _GL_MT_SAFE macro invocation should be attached to functions that are
+    multi-thread safe, possibly with specific constraints:
+
+      _GL_MT_SAFE( IF_DIFFERENT(argument...)
+                   // means that it is MT-safe as long as different threads
+                   // call the functions with different values for the
+                   // specified argument(s), not the same one.
+
+                   IF_MT_SAFE(argument...)
+                   // means that it is MT-safe as if the argument, a function
+                   // pointer, is multi-thread safe.
+
+                   IF_LOCKED(global_variable...)
+                   // means that it is MT-safe as long as all invocations
+                   // happen with the specified global variable(s) locked:
+                   // pthread_mutex_t instances - locked.
+                   // pthread_rwlock_t instances - wrlocked.
+
+                   IF_RDLOCKED(global_variable...)
+                   // means that it is MT-safe as long as all invocations
+                   // happen with the specified global variable(s) locked:
+                   // pthread_rwlock_t instances - rdlocked.
+
+                   IF_FIXED(global_variable...)
+                   // means that it is MT-safe as long as the specified
+                   // global variable(s), and the memory they point to
+                   // (directly or indirectly), are guaranteed not to be
+                   // modified.
+
+                   IF_NOT_CALLED(global_function...)
+                   // means that it is MT-safe as long as the specified
+                   // global function(s) are guaranteed not to be called.
+                 )
+
+      _GL_MT_SAFE() // means that it is MT-safe in the absolute sense.
+
+    A _GL_NOT_MT_SAFE macro invocation should be attached to functions that
+    are not multi-thread safe.  */
+#define _GL_MT_SAFE(...)
+#define _GL_NOT_MT_SAFE()
+])
   dnl Hint which direction to take regarding cross-compilation guesses:
   dnl When a user installs a program on a platform they are not intimately
   dnl familiar with, --enable-cross-guesses=conservative is the appropriate