gcc/fortran/doc/gfortran/compiler-characteristics/thread-safety-of-the-runtime-library.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: thread-safety, threads
   7
   8 .. _thread-safety-of-the-runtime-library:
   9
  10 Thread-safety of the runtime library
  11 ************************************
  12
  13 GNU Fortran can be used in programs with multiple threads, e.g. by
  14 using OpenMP, by calling OS thread handling functions via the
  15 ``ISO_C_BINDING`` facility, or by GNU Fortran compiled library code
  16 being called from a multi-threaded program.
  17
  18 The GNU Fortran runtime library, (``libgfortran``), supports being
  19 called concurrently from multiple threads with the following
  20 exceptions.
  21
  22 During library initialization, the C ``getenv`` function is used,
  23 which need not be thread-safe.  Similarly, the ``getenv``
  24 function is used to implement the ``GET_ENVIRONMENT_VARIABLE`` and
  25 ``GETENV`` intrinsics.  It is the responsibility of the user to
  26 ensure that the environment is not being updated concurrently when any
  27 of these actions are taking place.
  28
  29 The ``EXECUTE_COMMAND_LINE`` and ``SYSTEM`` intrinsics are
  30 implemented with the ``system`` function, which need not be
  31 thread-safe.  It is the responsibility of the user to ensure that
  32 ``system`` is not called concurrently.
  33
  34 For platforms not supporting thread-safe POSIX functions, further
  35 functionality might not be thread-safe.  For details, please consult
  36 the documentation for your operating system.
  37
  38 The GNU Fortran runtime library uses various C library functions that
  39 depend on the locale, such as ``strtod`` and ``snprintf``.  In
  40 order to work correctly in locale-aware programs that set the locale
  41 using ``setlocale``, the locale is reset to the default 'C'
  42 locale while executing a formatted ``READ`` or ``WRITE``
  43 statement.  On targets supporting the POSIX 2008 per-thread locale
  44 functions (e.g. ``newlocale``, ``uselocale``,
  45 ``freelocale``), these are used and thus the global locale set
  46 using ``setlocale`` or the per-thread locales in other threads are
  47 not affected.  However, on targets lacking this functionality, the
  48 global LC_NUMERIC locale is set to 'C' during the formatted I/O.
  49 Thus, on such targets it's not safe to call ``setlocale``
  50 concurrently from another thread while a Fortran formatted I/O
  51 operation is in progress.  Also, other threads doing something
  52 dependent on the LC_NUMERIC locale might not work correctly if a
  53 formatted I/O operation is in progress in another thread.