notation for documenting multithread-safety

[Bruno Haible]

Hi all,

Is anyone aware of a notation that allows to specify, unambiguously, under
which calls to a C function are multithread-safe?

I would like to start documenting the multithread-safety of the functions in
gnulib and other libraries (libunistring, libgettextpo, ...).

A simple annotation
  /* mt-safe */
won't do it, because many functions are only mt-safe in specific conditions.

I'm thinking of a more elaborated annotation
  /* mt-safe [if_different(argument ...)]
             [if_fixed(global_variable ...)]
             [if_locked(global_variable ...)]
             [if_mt_safe(argument ...)]
             [if_not_called(function ...)] */

with the following examples:

1)
  /* mt-safe if_different(cd) */
  size_t iconv (iconv_t cd,
                char **inbuf, size_t *inbytesleft,
                char **outbuf, size_t *outbytesleft);

  means that different threads can call iconv() at the same time on
  different iconv_t descriptors, but not on the same one.

2)
  /* mt-safe if_fixed(program_name) */
  void error (int status, int errnum, const char *message, ...);

  means that different threads can call error(), as long as no thread
  modifies or frees the program_name variable.

3)
  /* mt-safe if_locked(gettext_lock) */
  char * some_gettext_internal_function (...);

  means that different threads can call the some_gettext_internal_function,
  if all take care to lock gettext_lock during the call.

4)
  /* mt-safe if_mt_safe(func) */
  int pthread_once (pthread_once_t *once_control, void (*func) (void));

  means that if func is mt-safe, the calls to pthread_once with this
  function as argument are mt-safe as well. (It's a bad example: In this case,
  func will typically have side effects. What we actually want to express
  is that pthread_once does not have more side effects than func has.)

5)
  /* mt-safe if_not_called(setlocale) */
  char *nl_langinfo (nl_item item);

  means that different threads can call nl_langinfo(), as long as no thread
  invokes setlocale.

But before I reinvent the wheel, maybe it has already been invented?

Bruno