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 <[email protected]> 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
