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
- Move describe into a second submodule stats_more and build the three files. Which .smod file does the new submodule read?
- 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?
- Remove module from the header of mean inside stats_impl. What does gfortran say?
- 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.
-
What does the
moduleprefix 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.
-
What does
submodule (stats) stats_implname?Answer
The parent module and the submodule itself
The parent is in the parentheses, the submodule name follows.
-
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".
-
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 pAnswer
42
twice doubles its argument.
-
Which file does a program that says
use statsread?Answer
stats.mod
A user reads the module file, a submodule reads the smod file.
-
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.
-
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.
-
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.
-
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.
-
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