Document libgfortran thread-safety

From-SVN: r169864

gcc/fortran/ChangeLog

+2011-02-06  Janne Blomqvist  <jb@gcc.gnu.org>
+
+	* gfortran.texi (Thread-safety): New section.
+	* intrinsic.texi (EXECUTE_COMMAND_LINE): Mention thread-safety.
+	(GETENV): Likewise.
+	(GET_ENVIRONMENT_VARIABLE): Likewise.
+	(SYSTEM): Likewise.
+
 2011-02-06  Paul Thomas  <pault@gcc.gnu.org>
 
 	PR fortran/47592

gcc/fortran/gfortran.texi

@@ -1157,6 +1157,36 @@ representation of @code{LOGICAL} variables in GNU Fortran is identical
 to C99 _Bool, except for a possible difference in storage size
 depending on the kind.
 
+
+@node Thread-safety of the runtime library
+@section Thread-safety of the runtime library
+@cindex thread-safety, threads
+
+GNU Fortran can be used in programs with multiple threads, e.g. by
+using OpenMP, by calling OS thread handling functions via the
+@code{ISO_C_BINDING} facility, or by GNU Fortran compiled library code
+being called from a multi-threaded program.
+
+The GNU Fortran runtime library, (@var{libgfortran}), supports being
+called concurrently from multiple threads with the following
+exceptions. 
+
+During library initialization, the C @code{getenv()} function is used,
+which need not be thread-safe.  Similarly, the @code{getenv()}
+function is used to implement the @code{GET_ENVIRONMENT_VARIABLE} and
+@code{GETENV} intrinsics.  It is the responsibility of the user to
+ensure that the environment is not being updated concurrently when any
+of these actions are taking place.
+
+The @code{EXECUTE_COMMAND_LINE} and @code{SYSTEM} intrinsics are
+implemented with the @code{system()} function, which need not be
+thread-safe.  It is the responsibility of the user to ensure that
+@code{system()} is not called concurrently.
+
+Finally, for platforms not supporting thread-safe @code{POSIX}
+functions, further functionality might not be thread-safe.  For
+details, please consult the documentation for your operating system.
+
 @c ---------------------------------------------------------------------
 @c Extensions
 @c ---------------------------------------------------------------------

gcc/fortran/intrinsic.texi

@@ -4162,6 +4162,9 @@ the command, as returned by @code{system}.  @code{CMDSTAT} is set to zero
 if the command line was executed (whatever its exit status was).
 @code{CMDMSG} is assigned an error message if an error has occurred.
 
+Note that the @code{system()} call need not be thread-safe. It is the
+responsibility of the user to ensure that @code{system()} is not
+called concurrently.
 
 @item @emph{Standard}:
 Fortran 2008 and later
@@ -5452,11 +5455,15 @@ END PROGRAM
 @item @emph{Description}:
 Get the @var{VALUE} of the environmental variable @var{NAME}.
 
-This intrinsic routine is provided for backwards compatibility with 
-GNU Fortran 77.  In new code, programmers should consider the use of 
+This intrinsic routine is provided for backwards compatibility with
+GNU Fortran 77.  In new code, programmers should consider the use of
 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
 2003 standard.
 
+Note that @code{GETENV} need not be thread-safe. It is the
+responsibility of the user to ensure that the environment is not being
+updated concurrently with a call to the @code{GETENV} intrinsic.
+
 @item @emph{Standard}:
 GNU extension
 
@@ -5501,6 +5508,11 @@ END PROGRAM
 @item @emph{Description}:
 Get the @var{VALUE} of the environmental variable @var{NAME}.
 
+Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
+is the responsibility of the user to ensure that the environment is
+not being updated concurrently with a call to the
+@code{GET_ENVIRONMENT_VARIABLE} intrinsic.
+
 @item @emph{Standard}:
 Fortran 2003 and later
 
@@ -11779,6 +11791,10 @@ and environment-dependent.
 This intrinsic is provided in both subroutine and function forms;
 however, only one form can be used in any given program unit.
 
+Note that the @code{system()} call need not be thread-safe. It is the
+responsibility of the user to ensure that @code{system()} is not
+called concurrently.
+
 @item @emph{Standard}:
 GNU extension