StarPU Handbook
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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)

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
end program nf_initexit

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.