---

2.13 Shared-memory Coarrays ¶

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 libgfortran library, and is fully compatible with the ABI enabled when gfortran is invoked with -fcoarray=lib. Link the shared-memory coarray to the executable produced by gfortran using -lcaf_shmem.

The library 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 systems.

One can control some aspects of the library behavior at run time using environment variables:

GFORTRAN_NUM_IMAGES: The number of images to spawn when running the 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 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 running on.

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 (k or K suffix), megabytes (m or M) or gigabytes (g or 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 chosen. Note, although the size is set, most modern systems do not allocate the memory at 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 core dumps!

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 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 are overwritten without notice or may result in failure to start. These are: GFORTRAN_IMAGE_NUM, GFORTRAN_SHMEM_PID, and 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 the above variables from the environment.