ISO C 23, <stdlib.h>, and once_flag

[Bruno Haible]

In ISO C 23,
  - the type 'once_flag',
  - the macro ONCE_FLAG_INIT,
  - the declaration of function 'call_once'
are all available from <stdlib.h>, not only from <threads.h>.

1) This makes it clear that often call_once is needed in an application
without also needing mutexes. For this reason, I'm moving the 'call_once'
function definition out of the 'mtx' module, into a module of its own.

2) The requirement to have 'once_flag' defined in <stdlib.h> would mean
that Gnulib's stdlib.h replacement would have
  - to include <pthread.h> on Unix platforms, and
  - to include <windows.h> on native Windows.

Each of the two includes would cause a lot of trouble to users:
  - for <pthread.h>, by having many more cases of header file recursion
    (we had that often, and the workarounds were always ad-hoc),
  - for <windows.h>, by defining lots of identifiers in the namespace.

This is not worth the trouble, given that the workaround — include
<threads.h> instead of <stdlib.h> — is in the realm of ISO C and
very simple. I'm therefore not implementing ISO C 23 compatibility
on this point. We can revisit it in 10 years or so; then hopefully
some platforms will have restructured their header files and will
define 'once_flag' in <stdlib.h>.


2023-03-25  Bruno Haible  <bruno@clisp.org>

        stdlib: ISO C 23: Document issue with once_flag and call_once.
        * doc/posix-headers/stdlib.texi: Document issue and workaround.

2023-03-25  Bruno Haible  <bruno@clisp.org>

        call_once: New module, separate from mtx.
        * lib/threads.in.h (call_once): Declare as part of module 'call_once',
        not module 'mtx'.
        * lib/call_once.c: New file, extracted from lib/mtx.c.
        * lib/mtx.c (call_once): Remove function.
        * m4/threads_h.m4 (gl_THREADS_H_REQUIRE_DEFAULTS): Inititalize
        GNULIB_CALL_ONCE.
        * modules/threads-h (Makefile.am): Substitute GNULIB_CALL_ONCE.
        * modules/call_once: New file, based on modules/mtx.
        * modules/threads (Depends-on): Add call_once.
        * tests/test-threads-c++.cc: Update accordingly.
        * modules/call_once-tests: New file, based on modules/mtx-tests.
        * modules/mtx-tests (Files): Remove tests/test-call_once.c.
        (Makefile.am): Don't compile test-call_once.
        * doc/posix-functions/call_once.texi: Document that the relevant module
        is now 'call_once'.
        * NEWS: Mention the change.

0001-call_once-New-module-separate-from-mtx.patch
Description: Text Data

0002-stdlib-ISO-C-23-Document-issue-with-once_flag-and-ca.patch
Description: Text Data