Submodules

A module with a thousand lines of procedure bodies is one unit: a user of the module needs the interface, and the interface is the small part. Fortran 2008 split the two. The module keeps the declarations and a set of interface bodies marked module procedure; one or more submodules hold the implementation. This lesson writes both halves, builds a program that uses them, and reads the error that a mismatch between the declared interface and the code produces.

The module interface

The procedure is declared inside an ordinary interface block, with the module prefix in front of function or subroutine and nothing but the declarations inside. That prefix is what tells the compiler this body is written in a submodule; a procedure without it must have its body in the module itself.

The whole program below is one file: a module, a submodule and a program. One file is enough for the compiler, which reads from the top and has the parent's module files by the time it reaches the submodule, and it keeps the example in one place. The section after this one separates the three files and shows the build.

The file sub.f90:

module stats implicit none interface module function mean(a) result(m) real, intent(in) :: a(:) real :: m end function mean module subroutine describe(a, label) real, intent(in) :: a(:) character(len=*), intent(in) :: label end subroutine describe end interface end module stats submodule (stats) stats_impl implicit none contains module function mean(a) result(m) real, intent(in) :: a(:) real :: m m = sum(a) / size(a) end function mean module subroutine describe(a, label) real, intent(in) :: a(:) character(len=*), intent(in) :: label print '(a,a,f8.2)', label, ': mean ', mean(a) end subroutine describe end submodule stats_impl program subdemo use stats, only: mean, describe implicit none real :: x(5) x = [2.0, 4.0, 4.0, 4.0, 6.0] print '(a,f8.2)', 'mean = ', mean(x) call describe(x, 'summary') end program subdemo

gfortran -Wall -Wextra -std=f2018 sub.f90 -o sub
./sub

mean = 4.00
summary: mean 4.00

Two things are worth noticing in the run. The program sees only mean and describe, which it asked for with only; the submodule is invisible to it, and a name defined in the submodule alone cannot be used from outside the module. And describe calls mean through the module interface, so the two procedures cooperate exactly as they would if both bodies sat in the module.

The SUBMODULE

submodule (stats) stats_impl reads as: this unit implements part of the module stats, and its own name is stats_impl. The parent name in the parentheses is what the interface bodies belong to; the name after it is what a further submodule would name as its parent. Inside, each procedure repeats its header with the same module prefix and omits the body of the interface that the module already carries:

The file stats_impl.f90, the implementation on its own:

submodule (stats) stats_impl implicit none contains module function mean(a) result(m) real, intent(in) :: a(:) real :: m m = sum(a) / size(a) end function mean end submodule stats_impl

One submodule may hold every procedure of the module, or the procedures may be spread over several submodules, one per area of the code. The split is invisible to the users: they say use stats and the compiler finds the interface in stats.mod whatever file the body lives in.

Build order and .smod files

A submodule cannot be compiled first, and the message says which file is missing:

gfortran -Wall -Wextra -std=f2018 -c stats_impl.f90

f951: Fatal Error: Module file 'stats.smod' has not been generated, either because the module does not contain a MODULE PROCEDURE or there is an error in the module.
compilation terminated.

stats.smod is the companion of stats.mod: the module file tells a user what it may call, and the .smod file tells a submodule what it has to implement. The same code as three files, starting with the module, which is now only the interface:

The file stats.f90:

module stats implicit none interface module function mean(a) result(m) real, intent(in) :: a(:) real :: m end function mean end interface end module stats

The program, in main.f90, needs stats.mod and therefore comes after the module in the build:

program submain use stats, only: mean implicit none real :: x(4) x = [1.0, 2.0, 3.0, 4.0] print '(a,f8.2)', 'mean = ', mean(x) end program submain

With stats_impl.f90 from the section above, three compiles and a link build the program:

gfortran -Wall -Wextra -std=f2018 -c stats.f90
gfortran -Wall -Wextra -std=f2018 -c stats_impl.f90
gfortran -Wall -Wextra -std=f2018 -c main.f90
gfortran stats.o stats_impl.o main.o -o sub
./sub
ls

mean = 2.50
main.f90
main.o
stats.f90
stats.mod
stats.o
stats.smod
stats@stats_impl.smod
stats_impl.f90
stats_impl.o
sub

Three module files appear where a plain module writes one. stats.mod is the interface every user reads. stats.smod is the interface a submodule of stats reads. stats@stats_impl.smod is the file a submodule of stats_impl would read: the at sign joins the ancestor chain, so the chain of submodules is a folder of files, one per level.

That chain is the useful property. Editing the body of mean or describe changes stats_impl.o and nothing else: the .mod file is written by the module, the module did not change, so a file that says use stats does not have to be recompiled. In a project where a library interface changes once a month and its bodies change every day, that is the majority of a build.

The same caution as before applies to all of the generated files: they belong to one compiler version. A .mod or .smod written by another gfortran version is not readable by this one, which is why a build folder is not a thing to copy between machines.

Submodules of submodules

The parent of a submodule can be another submodule: submodule (geo:geo_impl) geo_more implements procedures of the module geo from inside a descendant of geo_impl. Both procedures are still declared in the module, so a program uses them through use geo and never sees the two levels.

The file anc.f90:

module geo implicit none interface module function area(w, h) result(a) real, intent(in) :: w, h real :: a end function area module subroutine report(w, h) real, intent(in) :: w, h end subroutine report end interface end module geo submodule (geo) geo_impl implicit none contains module function area(w, h) result(a) real, intent(in) :: w, h real :: a a = w * h end function area end submodule geo_impl submodule (geo:geo_impl) geo_more implicit none contains module subroutine report(w, h) real, intent(in) :: w, h print '(a,f8.2)', 'area = ', area(w, h) end subroutine report end submodule geo_more program anc use geo implicit none call report(3.0, 4.0) end program anc

gfortran -Wall -Wextra -std=f2018 anc.f90 -o anc
./anc

area = 12.00

report in the grandchild calls area, which its parent geo_impl implements. That is the normal use of the chain: a submodule may call anything declared in the module or implemented in an ancestor of its own line, and never anything from a sibling, which would be a dependency the compiler cannot check.

A mismatch in the implementation

The submodule's header must agree with the interface body in the module. A result of the wrong type is caught where the submodule declares it, with both declarations named in the message:

module stats implicit none interface module function mean(a) result(m) real, intent(in) :: a(:) real :: m end function mean end interface end module stats submodule (stats) stats_impl implicit none contains module function mean(a) result(m) real, intent(in) :: a(:) integer :: m m = int(sum(a) / size(a)) end function mean end submodule stats_impl program badprint use stats implicit none real :: x(4) x = [1.0, 2.0, 3.0, 4.0] print *, mean(x) end program badprint

gfortran -Wall -Wextra -std=f2018 bad.f90 -o bad

bad.f90:16:2:

16 | module function mean(a) result(m)
| 1
Error: Type mismatch in function result (INTEGER(4)/REAL(4)) between the MODULE PROCEDURE declaration in MODULE 'stats' and the declaration at (1) in (SUB)MODULE 'stats_impl'

The message names both sides, which is more than a plain module error gives: the compiler kept the interface in stats.mod and compared it with what it found in the submodule. Argument lists, intent, kinds and the result name are all checked the same way, and a mismatch stops the build before a program can be linked.

When a submodule pays

A submodule pays in three situations: a module whose bodies are long and whose interface changes rarely, because an edit then rebuilds one object file instead of every user; a library built by several people, where the interface is reviewed once and the implementations change daily; and C interoperability, where the body of a bind(c) procedure belongs in one place and its declaration in another.

It costs a file per implementation and one more rule to know, and it hides the body from a reader who starts at the module. For a program of a few hundred lines a plain module is easier to read, and the bodies belong in it. The mechanism is a build tool for large code, not a style that every program should adopt.

Exercises

  1. Move describe into a second submodule stats_more and build the three files. Which .smod file does the new submodule read?
  2. Add a private helper procedure to the submodule, without declaring it in the module, and call it from mean. Can a program outside the module call it?
  3. Remove module from the header of mean inside stats_impl. What does gfortran say?
  4. Change the interface body of describe so its second argument is character(len=20) and leave the implementation as it is. Read the error.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does the module prefix on a procedure inside an interface block mean?

    Answer

    The body is written in a submodule, not in the module

    It marks an interface body whose implementation is elsewhere.

  2. What does submodule (stats) stats_impl name?

    Answer

    The parent module and the submodule itself

    The parent is in the parentheses, the submodule name follows.

  3. Which file must exist before a submodule is compiled?

    Answer

    The parent .smod file

    The build stops with "Module file stats.smod has not been generated".

  4. What does this program print? module m implicit none interface module function twice(n) result(r) integer, intent(in) :: n integer :: r end function twice end interface end module m submodule (m) m_impl implicit none contains module function twice(n) result(r) integer, intent(in) :: n integer :: r r = 2 * n end function twice end submodule m_impl program p use m implicit none print *, twice(21) end program p

    Answer

    42

    twice doubles its argument.

  5. Which file does a program that says use stats read?

    Answer

    stats.mod

    A user reads the module file, a submodule reads the smod file.

  6. Why does editing a submodule body not force a rebuild of its users?

    Answer

    The .mod file of the module is unchanged

    A user depends on the interface, which lives in the .mod file.

  7. What does gfortran report for a result of the wrong type in a submodule?

    Answer

    Type mismatch in function result between the MODULE PROCEDURE declaration and the declaration in the submodule

    The interface body is compared with the implementation.

  8. What may a procedure inside a submodule call?

    Answer

    What the module declares and what its ancestors implement

    Sibling submodules are not visible to each other.

  9. What is stats@stats_impl.smod?

    Answer

    The interface file a submodule of stats_impl reads

    The at sign joins the ancestor chain of the submodule.

  10. When is a plain module easier than a module with a submodule?

    Answer

    When the module is small and the bodies change with the interface

    Splitting costs a file and a rule; it pays in large code.

The programs on this page were built with GNU Fortran (Alpine 15.2.0) 15.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev