https://gcc.gnu.org/g:1179e4ba4d1f47d54dd47abf159ffae64505b13f
commit r16-7739-g1179e4ba4d1f47d54dd47abf159ffae64505b13f Author: Jerry DeLisle <[email protected]> Date: Sun Feb 15 15:27:59 2026 -0800 Fortran: Cleanup documentation for coarray -lcaf_shmem. PR fortran/88076 gcc/fortran/ChangeLog: * invoke.texi: Use corrected english. Diff: --- gcc/fortran/invoke.texi | 73 ++++++++++++++++++++++++------------------------- 1 file changed, 36 insertions(+), 37 deletions(-) diff --git a/gcc/fortran/invoke.texi b/gcc/fortran/invoke.texi index c544037033a2..90836657af14 100644 --- a/gcc/fortran/invoke.texi +++ b/gcc/fortran/invoke.texi @@ -104,7 +104,7 @@ one is not the default. * Interoperability Options:: Options for interoperability with other languages. * Environment Variables:: Environment variables that affect @command{gfortran}. -* Shared Memory Coarrays:: Multi process shared memory coarray support. +* Shared-memory Coarrays:: Multiprocess shared-memory coarray support. @end menu @node Option Summary @@ -2307,64 +2307,63 @@ variables. run-time behavior of programs compiled with GNU Fortran. @c man end -@node Shared Memory Coarrays -@section Shared Memory Coarrays +@node Shared-memory Coarrays +@section Shared-memory Coarrays -@c man begin SHARED MEMORY COARRAYS +@c man begin SHARED-MEMORY COARRAYS -@command{gfortran} supplies a runtime library for running coarray enabled -programs using a shared memory multi process approach. The library is supplied -as a static link library with the @command{libgfortran} library and is fully -compatible with the ABI enabled when @command{gfortran} is called with -@code{-fcoarray=lib}. The shared memory coarray library then just needs to be -linked to the executable produced by @command{gfortran} using -@code{-lcaf_shmem}. +@command{gfortran} supplies a runtime library for running coarray-enabled +programs using a shared-memory multiprocess approach. The library is supplied +as a static link library with the @command{libgfortran} library, and is fully +compatible with the ABI enabled when @command{gfortran} is invoked with +@option{-fcoarray=lib}. Link the shared-memory coarray to the executable +produced by @command{gfortran} using @option{-lcaf_shmem}. The library @code{caf_shmem} can only be used on architectures that allow multiple processes to use the same memory at the same virtual memory address in -each process' memory space. This is the case on most Unix and Windows based +each process' memory space. This is the case on most Unix- and Windows-based systems. -The resulting executable can be started without any driver and does not provide -any additional command line options. Limited control is possible by +One can control some aspects of the library behavior at run time using environment variables: @env{GFORTRAN_NUM_IMAGES}: The number of images to spawn when running the -executable. Note, there will always be one additional supervisor process, which +executable. Note, there is always one additional supervisor process, which does not participate in the computation, but is only responsible for starting the images and catching any (ab-)normal termination. When the environment -variable is not set, then the number of hardware threads reported by the OS will -be taken. Over-provisioning is possible. The number of images is limited only +variable is not set, then the number of hardware threads reported by the OS is +used. Over-provisioning is possible. The number of images is limited only by the OS and the size of an integer variable on the architecture the program is -to be run on. +running on. -@env{GFORTRAN_SHARED_MEMORY_SIZE}: The size of the shared memory segment made -available to all images is fixed and needs to be set at program start. It can -not grow or shrink. The size can be given in bytes (no suffix), kilobytes +@env{GFORTRAN_SHARED_MEMORY_SIZE}: The size of the shared-memory segment made +available to all images is fixed and needs to be set at program start. It +cannot grow or shrink. The size can be given in bytes (no suffix), kilobytes (@code{k} or @code{K} suffix), megabytes (@code{m} or @code{M}) or gigabytes (@code{g} or @code{G}). If the variable is not set, or not parseable, then on -32-bit architectures 2^28 bytes and on 64-bit 2^34 bytes are choosen. Note, +32-bit architectures 2^28 bytes and on 64-bit 2^34 bytes are chosen. Note, although the size is set, most modern systems do not allocate the memory at -program start. This allows to choose a shared memory size larger than available -memory. +program start. This allows one to choose a shared-memory size larger than +available memory. -Warning: Choosing a large shared memory size may produce large coredumps! +Warning: Choosing a large shared-memory size may produce large core dumps! @env{GFORTRAN_IMAGE_RESTARTS_LIMIT}: On certain platforms, esp. MacOS, the -shared memory segment needs to be placed on the same (virtual) address in every -image or synchronisation primitives do not work as expected. Unfortunately are -some OSes somewhat arbitrary on when they can do this. When the OS is not able -to fullfill the request, then the image aborts itsself and is restarted by the -supervisor untill the OS complies. This environment variable limits the total -number of restarts of all images having an issue with shared memory segment +shared-memory segment needs to be placed on the same (virtual) address in every +image or synchronization primitives do not work as expected. Unfortunately some +operating systems are somewhat arbitrary on when they can do this. When the OS +is not able to fulfill the request, the image aborts itself and is restarted by the +supervisor until the OS complies. This environment variable limits the total +number of restarts of all images having an issue with shared-memory segment placement. The default value is 4000. -The shared memory coarray library internally uses some additional environment -variables, which will be overwritten without notice or may result in failure to -start. These are: @code{GFORTRAN_IMAGE_NUM}, @code{GFORTRAN_SHMEM_PID} and -@code{GFORTRAN_SHMEM_BASE}. It is strongly discouraged to use these variables. -Special care needs to be taken, when one coarray program starts another coarray +The shared-memory coarray library internally uses some additional environment +variables, which are overwritten without notice or may result in failure to +start. These are: @code{GFORTRAN_IMAGE_NUM}, @code{GFORTRAN_SHMEM_PID}, and +@code{GFORTRAN_SHMEM_BASE}. Using these variables is strongly discouraged. +Special care needs to be taken when one coarray program starts another coarray program as a child process. In this case it is the spawning process' -responsibility to remove above variables from the environment. +responsibility to remove the above variables from the environment. @c man end +
