StarPU Handbook - StarPU Language Bindings
|
StarPU provides the necessary routines and support to natively access most of its functionalities from Fortran 2008+ codes.
All symbols (functions, constants) are defined in fstarpu_mod.f90
. Every symbol of the Native Fortran support API is prefixed by fstarpu_
.
Note: Mixing uses of fstarpu_
and starpu_
symbols in the same Fortran code has unspecified behavior. See Valid API Mixes and Language Mixes for a discussion about valid and unspecified combinations.
The Native Fortran support relies on Fortran 2008 specific constructs, as well as on the support for interoperability of assumed-shape arrays introduced as part of Fortran's Technical Specification ISO/IEC TS 29113:2012, for which no equivalent are available in previous versions of the standard. It has currently been tested successfully with GNU GFortran 4.9, GFortran 5.x, GFortran 6.x and the Intel Fortran Compiler >= 2016. It is known not to work with GNU GFortran < 4.9, Intel Fortran Compiler < 2016.
See Section Using StarPU with Older Fortran Compilers for information on how to write StarPU Fortran code with older compilers.
The Native Fortran API is enabled and its companion fstarpu_mod.f90
Fortran module source file is installed by default when a Fortran compiler is found, unless the detected Fortran compiler is known not to support the requirements for the Native Fortran API. The support can be disabled through the configure
option --disable-fortran. Conditional compiled source codes may check for the availability of the Native Fortran Support by testing whether the preprocessor macro STARPU_HAVE_FC
is defined or not.
Several examples using the Native Fortran API are provided in StarPU's examples/native_fortran/
examples directory, to showcase the Fortran flavor of various basic and more advanced StarPU features.
The Fortran module fstarpu_mod.f90
installed in StarPU's include/
directory provides all the necessary API definitions. It must be compiled with the same compiler (same vendor, same version) as the application itself, and the resulting fstarpu_mod.o
object file must be linked with the application executable.
Each example provided in StarPU's examples/native_fortran/
examples directory comes with its own dedicated Makefile for out-of-tree build. Such example Makefiles may be used as starting points for building application codes with StarPU.
All these examples assume that the standard Fortran module iso_c_binding
is in use.
NULL
pointer A basic example is available in examples/native_fortran/nf_vector_scal.f90
.
The snippet below show an example of minimal StarPU code using the Native Fortran support. The program should use
the standard module iso_c_binding
as well as StarPU's fstarpu_mod
. The StarPU runtime engine is initialized with a call to function fstarpu_init
, which returns an integer status of 0 if successful or non-0 otherwise. Eventually, a call to fstarpu_shutdown
ends the runtime engine and frees all internal StarPU data structures.
Fortran does not have a construction similar to C variadic functions, on which starpu_task_insert() relies at the time of this writing. However, Fortran's variable length arrays of c_ptr
elements enable to emulate much of the convenience of C's variadic functions. This is the approach retained for implementing fstarpu_task_insert
.
The general syntax for using fstarpu_task_insert
is as follows:
There is thus a unique array argument (/ ... /)
passed to fstarpu_task_insert
which itself contains the task settings. Each element of the array must be of type type(c_ptr)
. The last element of the array must be C_NULL_PTR
.
Example extracted from nf_vector.f90:
The full example is available in examples/native_fortran/nf_vector.f90
.
Several StarPU structures that are expected to be passed to the C API, are replaced by function/subroutine wrapper sets to allocate, set fields and free such structure. This strategy has been preferred over defining native Fortran equivalent of such structures using Fortran's derived types, to avoid potential layout mismatch between C and Fortran StarPU data structures. Examples of such data structures wrappers include fstarpu_conf_allocate
and alike, fstarpu_codelet_allocate
and alike, fstarpu_data_filter_allocate
and alike.
Here is an example of allocating, filling and deallocating a codelet structure:
The full example is available in examples/native_fortran/nf_vector.f90
.
When using older compilers, Fortran applications may still interoperate with StarPU using C marshalling functions as examplified in StarPU's examples/fortran/
and examples/fortran90/
example directories, though the process will be less convenient.
Basically, the main FORTRAN code calls some C wrapper functions to submit tasks to StarPU. Then, when StarPU starts a task, another C wrapper function calls the FORTRAN routine for the task.
Note that this marshalled FORTRAN support remains available even when specifying configure
option --disable-fortran (which only disables StarPU's native Fortran layer).
Mixing uses of fstarpu_
and starpu_
symbols in the same Fortran code has unspecified behavior. Using fstarpu_
symbols in C code has unspecified behavior.
For multi-language applications using both C and Fortran source files:
starpu_
symbols exclusivelyfstarpu_
symbols exclusively, or starpu_
symbols exclusively. Every other combination has unspecified behavior.