StarPU Handbook

The StarPU Native Fortran Support

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 behaviour. See Valid API Mixes and Language Mixes for a discussion about valid and unspecified combinations.

# Implementation Details and Specificities

## Prerequisites

The Native Fortran support relies on Fortran 2008 specific constructs, as well as on the support of 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 on information on how to write StarPU Fortran code with older compilers.

## Configuration

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.

## Examples

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.

## Compiling a Native Fortran Application

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 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.

# Fortran Translation for Common StarPU API Idioms

All these examples assume that the standard Fortran module `iso_c_binding` is in use.

- Specifying a `NULL` pointer
  type(c_ptr) :: my_ptr ! variable to store the pointer
  ! [...]
  my_ptr = c_null_ptr ! assign standard constant for null ptr
- Obtaining a pointer to some object:
  real(8), dimension(:), allocatable, target :: va
  type(c_ptr) :: p_va ! variable to store a pointer to array va
  ! [...]
  p_va = c_loc(va)
- Obtaining a pointer to some subroutine:
  ! pointed routine definition
  recursive subroutine myfunc () bind(C)
  ! [...]
  type(c_funptr) :: p_fun ! variable to store the routine pointer
  ! [...]
  p_fun = c_funloc(my_func)
- Obtaining the size of some object:
  real(8) :: a
  integer(c_size_t) :: sz_a ! variable to store the size of a
  ! [...]
  sz_a = c_sizeof(a)
- Obtaining the length of an array dimension:
  real(8), dimension(:,:), allocatable, target :: vb
  intger(c_int) :: ln_vb_1 ! variable to store the length of vb's dimension 1
  intger(c_int) :: ln_vb_2 ! variable to store the length of vb's dimension 2
  ! [...]
  ln_vb_1 = 1+ubound(vb,1)-lbound(vb,1) ! get length of dimension 1 of vb
  ln_vb_2 = 1+ubound(vb,2)-lbound(vb,2) ! get length of dimension 2 of vb
- Specifying a string constant:
  type(c_ptr) :: my_cl ! a StarPU codelet
  ! [...]
  ! set the name of a codelet to string 'my_codele't:
  call fstarpu_codelet_set_name(my_cl, c_char_"my_codelet"//c_null_char)
  ! note: using the C_CHAR_ prefix and the //C_NULL_CHAR concatenation at the end ensures
  ! that the string constant is properly '\0' terminated, and compatible with StarPU's
  ! internal C routines
  !
  ! note: plain Fortran string constants are not '\0' terminated, and as such, must not be
  ! passed to starpu routines.
- Combining multiple flag constants with a bitwise 'or':
  type(c_ptr) :: my_cl ! a pointer for the codelet structure
  ! [...]
  ! add a managed buffer to a codelet, specifying both the Read/Write access mode and the Locality hint
  call fstarpu_codelet_add_buffer(my_cl, fstarpu_rw.ior.fstarpu_locality)

# Uses, Initialization and Shutdown

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.

program nf_initexit
use iso_c_binding ! C interfacing module
use fstarpu_mod ! StarPU interfacing module
implicit none ! Fortran recommended best practice
integer(c_int) :: err ! return status for fstarpu_init
! initialize StarPU with default settings
err = fstarpu_init(c_null_ptr)
if (err /= 0) then
stop 1 ! StarPU initialization failure
end if
! - add StarPU Native Fortran API calls here
! shut StarPU down
call fstarpu_shutdown()
end program nf_initexit
fstarpu_mod::fstarpu_shutdown
Definition: fstarpu_mod.f90:206

# Fortran Flavor of StarPU's Variadic Insert_task

Fortran does not have a construction similar to C variadic functions on which starpu_insert_task() 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_insert_task`.

The general syntax for using `fstarpu_insert_task` is as follows:

call fstarpu_insert_task((/ <codelet ptr> &
[, <access mode flags>, <data handle>]* &
[, <argument type constant>, <argument>]* &
, c_null_ptr /))

There is thus a unique array argument `(/ ... /)` passed to `fstarpu_insert_task` 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:

call fstarpu_insert_task((/ cl_vec, & ! codelet
fstarpu_r, dh_va, & ! a first data handle
fstarpu_rw.ior.fstarpu_locality, dh_vb, & ! a second data handle
c_null_ptr /)) ! no more args

# Functions and Subroutines Expecting Data Structures Arguments

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 prefered 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:

! a pointer for the codelet structure
type(c_ptr) :: cl_vec
! [...]
! allocate an empty codelet structure
cl_vec = fstarpu_codelet_allocate()
! add a CPU implementation function to the codelet
call fstarpu_codelet_add_cpu_func(cl_vec, c_funloc(cl_cpu_func_vec))
! set the codelet name
call fstarpu_codelet_set_name(cl_vec, c_char_"my_vec_codelet"//c_null_char)
! add a Read-only mode data buffer to the codelet
call fstarpu_codelet_add_buffer(cl_vec, fstarpu_r)
! add a Read-Write mode data buffer to the codelet
call fstarpu_codelet_add_buffer(cl_vec, fstarpu_rw.ior.fstarpu_locality)
! [...]
! free codelet structure
call fstarpu_codelet_free(cl_vec)

# Additional Notes about the Native Fortran Support

## Using StarPU with Older Fortran Compilers

When using older compilers, Fortran applications may still interoperate with StarPU using C marshalling functions as exemplified 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).

## Valid API Mixes and Language Mixes

Mixing uses of `fstarpu_` and `starpu_` symbols in the same Fortran code has unspecified behaviour. Using `fstarpu_` symbols in C code has unspecified behaviour.

For multi-language applications using both C and Fortran source files:

- C source files must use `starpu_` symbols exclusively
- Fortran sources must uniformly use either `fstarpu_` symbols exclusively, or `starpu_` symbols exclusively. Every other combination has unspecified behaviour.